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

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

המרת כתובות של מקומות לקואורדינטות (geocoding) מאפשרת לכם לאחזר כתובת ממזהה מקום.

מזהי מקומות מזהים באופן ייחודי מקום במסד הנתונים של Google Places וב-מפות Google. אפשר לאחזר מזהי מקומות כשמבצעים גיאו-קידוד של כתובת. אפשר גם לאחזר מזהה מקום מממשקי API רבים אחרים, כמו Place Details (New),‏ חיפוש טקסט (New) ו-חיפוש בקרבת מקום (New).

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

בקשה לגיאו-קידוד של מקום היא בקשת GET של HTTP מהסוג הבא:

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

כאשר PLACE_ID מכיל את מזהה המקום של המיקום שהתעניינו בו.

מעבירים את כל שאר הפרמטרים כפרמטרים של כתובת URL, או, במקרה של פרמטרים כמו מפתח ה-API או מסכת השדה, בכותרות כחלק מבקשת ה-GET. לדוגמה:

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

או בפקודת curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

שימוש ב-OAuth כדי לשלוח בקשה

‫Geocoding API v4 תומך ב-OAuth 2.0 לאימות. כדי להשתמש ב-OAuth עם Geocoding API, צריך להקצות לטוקן OAuth את ההיקף הנכון. ‫Geocoding API תומך בהיקפים הבאים לשימוש בקידוד גאוגרפי של מקומות:

  • https://www.googleapis.com/auth/maps-platform.geocode ‫— לשימוש בכל ה-methods של Geocoding API.
  • https://www.googleapis.com/auth/maps-platform.geocode.place ‫— אפשר להשתמש רק עם GeocodePlace להמרת כתובות של מקומות לקואורדינטות (geocoding).

בנוסף, אפשר להשתמש בהיקף הכללי https://www.googleapis.com/auth/cloud-platform לכל ה-methods של Geocoding API. ההיקף הזה שימושי במהלך הפיתוח, אבל לא בייצור, כי זה היקף כללי שמאפשר גישה לכל השיטות.

מידע נוסף ודוגמאות זמינים במאמר בנושא שימוש ב-OAuth.

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

גיאו-קידוד של מקום מחזיר אובייקט GeocodeResult שמייצג את המקום שמתאים למזהה המקום.

תשובות של Geocoding API כוללות מערכי types בשני מקומות עיקריים בתוך GeocodeResult:

  1. ‫GeocodeResult.types: מערך שמציין את הסוגים הכוללים של התוצאה. הערכים האפשריים מופיעים בטבלה א' ובטבלה ב' בדף 'סוגי מקומות (חדש)'.
  2. ‫GeocodeResult.addressComponents[].types: לכל רכיב בכתובת יש מערך types שמציין את הסוג של החלק הספציפי הזה בכתובת. הערכים האלה מופיעים בטבלה סוגי כתובות וסוגי רכיבי כתובות בדף 'סוגי מקומות (חדש)'.

אובייקט ה-JSON המלא הוא מהצורה:

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "addressComponents": [
    {
      "longText": "1600",
      "shortText": "1600",
      "types": [
        "street_number"
      ]
    },
    {
      "longText": "Amphitheatre Parkway",
      "shortText": "Amphitheatre Pkwy",
      "types": [
        "route"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Mountain View",
      "shortText": "Mountain View",
      "types": [
        "locality",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Santa Clara County",
      "shortText": "Santa Clara County",
      "types": [
        "administrative_area_level_2",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "California",
      "shortText": "CA",
      "types": [
        "administrative_area_level_1",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "United States",
      "shortText": "US",
      "types": [
        "country",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "94043",
      "shortText": "94043",
      "types": [
        "postal_code"
      ]
    }
  ],
  "types": [
    "establishment",
    "point_of_interest"
  ]
}

פרמטרים נדרשים

  • ‫place — מזהה המקום של המקום שרוצים לקבל את הכתובת שלו שקלה לקריאה. מזהה המקום הוא מזהה ייחודי שאפשר להשתמש בו עם Google APIs אחרים. לדוגמה, אפשר להשתמש ב-placeID שמוחזר על ידי Roads API כדי לקבל את הכתובת של נקודה שהוצמדה לכביש. מידע נוסף על מזהי מקומות זמין במאמר מזהי מקומות.

פרמטרים אופציונליים

  • languageCode

    השפה שבה יוחזרו התוצאות.

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

  • regionCode

    קוד האזור כערך קוד CLDR באורך שני תווים. אין ערך ברירת מחדל. רוב הקודים של CLDR זהים לקודים של ISO 3166-1.

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

  • FieldMask

    יוצרים מסכת שדות תגובה כדי לציין את השדות שיוחזרו בתגובה. מעבירים את מסכת שדות התגובה לשיטה באמצעות פרמטר כתובת ה-URL ‏$fields או fields, או באמצעות כותרת ה-HTTP ‏X-Goog-FieldMask. לדוגמה, הבקשה שלמטה תחזיר רק את השדה formattedAddress של התגובה.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    התשובה היא: 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

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