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

מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

שימוש והיקף הכיסוי

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

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

מבנה

כניסות

premise

premise

subpremise

subpremise

point_of_interest

point_of_interest

street_address

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

פרטי הבקשה

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

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

בקשה לדוגמה

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

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJl2tj2-62j4ARzKWl1WCXLJI&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

    מזהה המקום של הבניין ב-buildings[] שמכיל את הכניסה הזו. כך תוכלו לזהות אילו מבנים מכילים אילו כניסות. הכניסה הזו תואמת לבניין שמופיע במדד i ב-buildings[], כאשר buildings[i].place_id שווה ל-building_place_id של הכניסה הזו. הערך הזה שונה ממזהה המקום של תוצאת הניתוח הגיאוגרפי, אלא אם תוצאת הניתוח הגיאוגרפי היא של הבניין עצמו. הפרמטר הזה לא תמיד מאוכלס.

  • entrance_tags[]

    מערך של תגי כניסה שמתארים את המאפיינים של הכניסה. הערך הבא נתמך:

    • "PREFERRED"

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

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

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

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

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

התגובה לבקשה לדוגמה שלמעלה כוללת שתי כניסות ובניין אחד עם קו מתאר. שימו לב ש-building_place_id של כל כניסה תואם ל-place_id של הבניין:

{
  "entrances": [
    {
        "building_place_id" : "ChIJU1erIO-2j4ARzlavxpYBJr8",
        "location" :
        {
          "lat" : 37.3736684,
          "lng" : -122.0540469
        },
        "entrance_tags": ["PREFERRED"]
    },
    {
        "building_place_id" : "ChIJU1erIO-2j4ARzlavxpYBJr8",
        "location" :
        {
          "lat" : 37.3738239,
          "lng" : -122.0539773
        },
    }
  ],
  "buildings" : [
    {
      "building_outlines" : [
        {
          "display_polygon" : {
            "coordinates" : [
              [
                [
                  -122.054453349467,
                  37.3742345734776
                ],
                [
                  -122.054665964955,
                  37.3737591984554
                ],
                [
                  -122.054080317537,
                  37.3735936952922
                ],
                [
                  -122.053867527481,
                  37.374069124071
                ],
                [
                  -122.054453349467,
                  37.3742345734776
                ]
              ]
            ],
            "type" : "Polygon"
          }
        }
      ],
      "place_id" : "ChIJU1erIO-2j4ARzlavxpYBJr8"
    }
  ],
}

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

ב-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. אובייקט building_outlines יחיד שמייצג כמה פוליגונים.
  2. תגובה עם כמה מבנים במערך buildings[].

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

"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 שלמעלה, אנחנו יכולים להציג את שני קווי המתאר של הבניינים במפה:

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

משוב

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