קווים כלליים של מבנים וכניסות

אתם יכולים להשתמש ב-Geocoding API כדי לקבל קווי מתאר של מבנים וכניסות, וכך לשפר את התצוגה החזותית של הנתונים ברנדרינג של המפה.

כדי לעשות זאת, צריך לכלול פרמטר נוסף בבקשת הגיאוקוד כדי להחזיר זוגות של קואורדינטות קו הרוחב/קו האורך שמגדירים את קווי המתאר של הבניין או את הכניסה. אתם יכולים להשתמש בפלט של הבקשות כדי לצייר קווי מתאר של מבנים ולציין את הכניסות למבנים במפה.

  • הקווים הכלליים של בניין הם קבוצה של זוגות קואורדינטות של קו הרוחב/קו האורך שמגדירים פוליגון דו-ממדי שמייצג את שטח כדור הארץ שמכוסה על ידי הבניין.
  • כניסה לבניין היא זוג קואורדינטות של קו אורך ורוחב שמגדיר את המיקום של נקודת הכניסה והיציאה למקום.

שימוש והיקף

אפשר להשתמש בשירות כדי להחזיר פוליגונים של קווי מתאר של מקום יחיד בבקשה אחת. כלומר, בקשה לקואורדינטות גיאוגרפיות ברמת העיר, כמו לונדון, בריטניה, לא מחזירה את כל קווי המתאר של המבנים באותה יישוב. במקרים כאלה, השירות יחזיר תגובה רגילה של קידוד גיאוגרפי ללא קווי מתאר או כניסות של מבנים. באופן ספציפי, השירות יוצר קווי מתאר ומבואות רק לסוגים הבאים של מקומות:

סוגי המקומות הנתמכים

מבנה

כניסות

premise

premise

subpremise

subpremise

point_of_interest

point_of_interest

street_address

התכונה הזו זמינה בכל האזורים, אבל הכיסוי משתנה בהתאם לאזור. בנוסף, צפויות להגיע תשובות מ-API שמכילות קווים כלליים של בניין, אבל לא נתוני כניסה. במקרה כזה, השירות יחזיר תגובה של המרה לקואורדינטות (geocoding) עם קווי מתאר של בניין, אבל לא מערך של נתוני כניסה. אנחנו כל הזמן פועלים לשיפור הכיסוי של הכניסות.

פרטי הבקשה

אפשר לקבל את קווי המתאר של הבניין ואת קואורדינטות הכניסה בבקשות מהסוגים הבאים:

בכל אחת מהבקשות האלה, צריך לציין את הפרמטר הזה: extra_computations=BUILDING_AND_ENTRANCES.

בקשה לדוגמה

בשאילתה הבאה נעשה שימוש במיקום גיאוגרפי של מקום כדי לקבל מידע על הכניסה ועל קווי המתאר של מסעדה במאונטיין ויו, קליפורניה, ארה"ב:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJ4TTDdzS3j4AR78EQgu5EADA&extra_computations=BUILDING_AND_ENTRANCES&key=YOUR_API_KEY

דוגמה לתשובה

ברוב המקרים, התשובה מחזירה שדות שתואמים לבניין אחד, אבל במקרים מסוימים התשובה יכולה לכלול כמה רכיבים, כמו נקודות עניין שנמצאות בכמה בניינים. רכיבי התשובה כוללים שני מערכי משנה:

מערך buildings[] עם השדות הבאים:

  • place_id

    המזהה הייחודי של הבניין. פרטים נוספים זמינים בסקירה הכללית על מזהי מקומות.

  • building_outlines[]

    מערך של קווי מתאר שמשויכים לבניין. למערך הזה יש רק רשומה אחת. לכל אובייקט ב-building_outlines[] יש את השדה הבא:

    • display_polygon

    הקידוד של GeoJSON של הפוליגון שמשויך לשטח הקרקע שמכוסה על ידי המבנה, באמצעות פורמט RFC 7946.

מערך entrances[] עם השדות הבאים:

  • location

    קואורדינטות קו הרוחב/קו האורך של הכניסה.

  • building_place_id

    מזהה המקום של הבניין שמכיל את הכניסה. הוא שונה ממזהה המקום של תוצאת הגיאוקוד, אלא אם תוצאת הגיאוקוד היא של הבניין עצמו. הפרמטר הזה לא תמיד מאוכלס.

התשובה מהשאילתה שלמעלה מראה כניסה אחת ופריט פוליגון אחד במערך המבנים:

{
  "entrances": [
    {
      "location": {
        "lat": 37.3925065,
        "lng": -122.0799465
      },
      "building_place_id": "ChIJVeHddzS3j4ARFZJVu4Cf27o"
    }
  ],
  "buildings" : [
    {
      "building_outlines" : [
        {
          "display_polygon" : {
            "coordinates" : [
              [
                [
                    -122.080188246116,
                    37.3926407183216
                ],
                [
                    -122.080281351765,
                    37.3924887558601
                ],
                [
                    -122.080023707261,
                    37.392390122414
                ],
                [
                    -122.079926266852,
                    37.3925369491992
                ],
                [
                    -122.080188246116,
                    37.3926407183216
                ]
              ]
            ],
            "type" : "Polygon"
          }
        }
      ],
      "place_id" : "ChIJVeHddzS3j4ARFZJVu4Cf27o"
    }
  ],
}

הצגת קווי מתאר של מבנים במפה

ב-JavaScript API יש תמיכה מובנית להצגת פוליגונים ופוליגונים מרובי צדדים בפורמט RFC 7946. כדי לעשות זאת:

  1. יוצרים אובייקט של מאפיין באמצעות נתוני הפוליגון.
  2. מחילים סגנון על הפוליגון.
  3. מחברים את התכונה לאובייקט המפה של JavaScript.

כל אובייקט במערך buildings מכיל אובייקט יחיד במערך building_outlines. הדוגמה הבאה מראה איך להציג את קווי המתאר של בניין במפה:

//This function takes an argument of 'buildings', which is the buildings[] array returned by the API.
async function displayBuildingOutline(buildings) {
    try {
        //Import the Google Maps Data library.
        const { Data } = await google.maps.importLibrary("maps")
        //Loop though the array of building outlines.
        buildings.forEach(building => {
            const features = []
            const buildingOutlines = building.building_outlines;
            //Add each building outline to a Feature object, and push this to an array of Features.
            buildingOutlines.forEach(buildingOutline => {
                const feature = {
                    type: "Feature",
                    properties: {},
                    geometry: buildingOutline.display_polygon
                }
                features.push(feature);
            });
            //Create a new Google Maps Data object, and apply styling.
            //We also assume the reference to the map on the page is named 'map'.
            //This applies the Data object to the map on the page.
            outlineLayer = new google.maps.Data({
                map,
                style: {
                    strokeColor: "#0085cc",
                    strokeOpacity: 1,
                    strokeWeight: 2,
                    fillColor: "#88d4fc",
                    fillOpacity: 0.5,
                },
            });
            //Add the array of Features created earlier to the Data object, as GeoJson.
            outlineLayer.addGeoJson({
                type: "FeatureCollection",
                features: features,
            });
        });
    } catch (e) {
        console.log('Building outlines failed. Error: ' + e)
    }
}

באמצעות הקוד שלמעלה, מתבצע עיבוד של קווי המתאר של הבניין שהוחזר על ידי Geocoding API בתשובה לדוגמה שצוינה קודם במסמך הזה, כך שהוא יופיע במפה באופן הבא:

קווי המתאר של המבנה מוצגים במפה

מקרי קצה

יכול להיות שתיתקלו גם בתרחישים הקיצוניים הבאים, אבל קוד הדוגמה שלמעלה עדיין יפעל בהם:

  1. תשובה עם כמה קווי מתאר של מבנים.
  2. אובייקט building_outlines יחיד שמייצג כמה פוליגונים.

לדוגמה, התשובה למזהה המקום ChIJGxgH9QBVHBYRl13JmZ0BFgo מכילה שתי תוצאות של מערך building_outlines[]:

"buildings": [
    {
        "building_outlines": [
            {
                "display_polygon": {
                    "coordinates": [
                        [
                            [
                                44.3313253363354,
                                13.636033631612
                            ],
                            [
                                44.3312576355624,
                                13.6362094887862
                            ],
                            [
                                44.3310854239923,
                                13.6361461767801
                            ],
                            [
                                44.3311531250111,
                                13.6359703194634
                            ],
                            [
                                44.3313253363354,
                                13.636033631612
                            ]
                        ]
                    ],
                    "type": "Polygon"
                }
            }
        ],
        "place_id": "ChIJ24NWUBhUHBYRSEmPBFa1wgc"
    },
    {
        "building_outlines": [
            {
                "display_polygon": {
                    "coordinates": [
                        [
                            [
                                44.330737534504,
                                13.6357057440832
                            ],
                            [
                                44.3307248314371,
                                13.6357390350529
                            ],
                            [
                                44.3306985591742,
                                13.635729486373
                            ],
                            [
                                44.3307114066013,
                                13.6356960265536
                            ],
                            [
                                44.330737534504,
                                13.6357057440832
                            ]
                        ]
                    ],
                    "type": "Polygon"
                }
            }
        ],
        "place_id": "ChIJpzQOABlUHBYRxiOC9goY1fE"
    }
]

באמצעות דוגמת הקוד של JavaScript שלמעלה, אנחנו יכולים להציג את שתי קווי המתאר במפה:

שני קווי מתאר של מבנים מוצגים במפה

משוב

זוהי תכונה ניסיונית. נשמח לקבל משוב בכתובת buildings-in-geocoding-feedback-channel@google.com.