בקשה ותשובה של מתארי כתובת

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

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

פרמטרים נוספים

אפשר להפעיל את תיאורי הכתובות באמצעות הפרמטר extra_computations. כדי לקבל תיאורי כתובות בתשובה, צריך לכלול את extra_computations=ADDRESS_DESCRIPTORS בבקשה להמרת כתובות לקואורדינטות (geocoding), בבקשה להמרת קואורדינטות לכתובות (reverse geocoding) או בבקשה להמרת מקומות לקואורדינטות (places geocoding).

דוגמה להמרת כתובות לקואורדינטות

השאילתה הבאה מכילה את הכתובת של מקום בדלהי:

https://maps.googleapis.com/maps/api/geocode/json?address=4118,+Kalan+Mehal+Chandni+Chowk,+New+Delhi&extra_computations=ADDRESS_DESCRIPTORS&key=YOUR_API_KEY

דוגמה לגיאו-קידוד של מקומות

השאילתה הבאה מכילה את מזהה המקום של מקום בדלהי:

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

דוגמה בהמרת קואורדינטות לכתובות (reverse geocoding)

השאילתה הבאה מכילה את הערך של קו הרוחב וקו האורך של מיקום בדלהי:

https://maps.googleapis.com/maps/api/geocode/json?latlng=28.640964,77.235875&extra_computations=ADDRESS_DESCRIPTORS&key=YOUR_API_KEY

תשובה

דוגמה ל-address_descriptor:

{
  "address_descriptor" : {
     "areas" : [
        {
           "containment" : "OUTSKIRTS",
           "display_name" : {
              "language_code" : "en",
              "text" : "Turkman Gate"
           },
           "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
        },
        {
           "containment" : "OUTSKIRTS",
           "display_name" : {
              "language_code" : "en",
              "text" : "Chandni Chowk"
           },
           "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
        },
        {
           "containment" : "NEAR",
           "display_name" : {
              "language_code" : "en",
              "text" : "Katar Ganj"
           },
           "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
        }
     ],
     "landmarks" : [
        {
           "display_name" : {
              "language_code" : "en",
              "text" : "Delite Cinema"
           },
           "straight_line_distance_meters" : 29.9306755065918,
           "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
           "travel_distance_meters" : 418.7794799804688,
           "spatial_relationship" : "ACROSS_THE_ROAD",
           "types" : [ "establishment", "movie_theater", "point_of_interest" ]
        },
        {
           "display_name" : {
              "language_code" : "en",
              "text" : "YES Bank"
           },
           "straight_line_distance_meters" : 66.83731079101562,
           "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
           "travel_distance_meters" : 489.0340270996094,
           "spatial_relationship" : "DOWN_THE_ROAD",
           "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
        },
        {
           "display_name" : {
              "language_code" : "en",
              "text" : "UCO Bank"
           },
           "straight_line_distance_meters" : 25.38849639892578,
           "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
           "travel_distance_meters" : 403.2246398925781,
           "spatial_relationship" : "ACROSS_THE_ROAD",
           "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
        },
        {
           "display_name" : {
              "language_code" : "en",
              "text" : "Delhi By Cycle Meeting Point"
           },
           "straight_line_distance_meters" : 44.02867126464844,
           "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
           "travel_distance_meters" : 97.41281890869141,
           "spatial_relationship" : "AROUND_THE_CORNER",
           "types" : [
              "establishment",
              "point_of_interest",
              "tourist_attraction",
              "travel_agency"
           ]
        },
        {
           "display_name" : {
              "language_code" : "en",
              "text" : "Axis Bank Branch"
           },
           "straight_line_distance_meters" : 102.3495178222656,
           "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
           "travel_distance_meters" : 330.8566284179688,
           "spatial_relationship" : "DOWN_THE_ROAD",
           "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
        }
     ]
  }
}

כל אובייקט address_descriptor מכיל שני מערכים: landmarks ו-areas. מערך landmarks מכיל עד 5 תוצאות שמדורגות לפי מידת הרלוונטיות שלהן. הדירוג מתבסס על הקרבה לקואורדינטות המבוקשות, על השכיחות של נקודת הציון ועל מידת החשיפה שלה. כל תוצאה של ציון דרך מכילה את הערכים הבאים:

  • ‫place_id הוא מזהה המקום של תוצאת ציוני הדרך. מידע נוסף על מזהה מקום
  • ‫display_name הוא השם המוצג של נקודת הציון, והוא מכיל את הערכים language_code ו-text.
  • ‫straight_line_distance_meters הוא המרחק בין נקודה לנקודה במטרים בין קואורדינטת הקלט לבין תוצאת ציוני הדרך.
  • ‫travel_distance_meters הוא המרחק במטרים שעברתם ברשת הכבישים (תוך התעלמות מהגבלות על הכבישים) בין קואורדינטת הקלט לבין תוצאת ציוני הדרך.
  • ‫spatial_relationship הוא הקשר המשוער בין קואורדינטת הקלט לבין תוצאת נקודות הציון:
    • ‫"NEAR" היא ברירת המחדל אם אף אחת מהאפשרויות הבאות לא מתקיימת.
    • "WITHIN" אם הקואורדינטות של הקלט נמצאות בתוך הגבולות של המבנה שמשויך לנקודת הציון.
    • ‫"BESIDE" כשהקואורדינטות של הקלט סמוכות ישירות לנקודת הציון או לנקודת הגישה שלה.
    • ‫"ACROSS_THE_ROAD" כשהקואורדינטה של נקודת ההתחלה נמצאת בדיוק מול נקודת הציון, בצד השני של המסלול.
    • ‫"DOWN_THE_ROAD" כשהקואורדינטות של הקלט נמצאות לאורך אותו מסלול כמו נקודת הציון, אבל לא "BESIDES" או "ACROSS_THE_ROAD".
    • "AROUND_THE_CORNER" כשהקואורדינטות של נקודת המוצא נמצאות לאורך מסלול ניצב לנקודת הציון (מוגבל לפנייה אחת).
    • "BEHIND" כשהקואורדינטות של הקלט קרובות למבנה, אבל רחוקות מנקודת הגישה שלו.
  • ‫types הם סוגי המקומות של נקודת הציון.

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

  • ‫place_id הוא מזהה המקום של תוצאת האזורים. מידע נוסף על מזהה מקום
  • ‫display_name הוא השם המוצג של האזור, והוא מכיל את language_code ואת text.
  • ‫containment הוא קשר ההכלה המשוער בין קואורדינטת הקלט לבין תוצאת האזורים:
    • ‫"NEAR" היא ברירת המחדל אם אף אחת מהאפשרויות הבאות לא מתקיימת.
    • ‫"WITHIN" כשהקואורדינטות של הקלט קרובות למרכז האזור.
    • ‫"OUTSKIRTS" כשהקואורדינטות של הקלט קרובות לקצה האזור.

כיסוי

תיאורי כתובות זמינים בכל האזורים. פרטים נוספים מופיעים במאמר בנושא כיסוי אזורים.

משוב

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