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

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

המזהה הייחודי של מקום במסד הנתונים של 'מקומות Google' ובמפות Google. אחזור מזהי מקומות כשממירים כתובת לקואורדינטות. אפשר גם לאחזר מזהה מקום מממשקי API רבים אחרים, כמו פרטי מקום (חדש), חיפוש טקסט (חדש) וחיפוש בקרבת מקום (חדש).

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

בקשת גיאוקוד של מקום היא בקשת HTTP GET בפורמט הבא:

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

כאשר PLACE_ID מכיל את מזהה המקום של המיקום הרצוי.

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

https://geocode.googleapis.com/v4beta/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/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

שימוש ב-OAuth לשליחת בקשה

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

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

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

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

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

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

אובייקט ה-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 API אחרים. לדוגמה, אפשר להשתמש ב-placeID שמוחזר על ידי Roads API כדי לקבל את הכתובת של נקודה שמוצמדת. מידע נוסף על מזהי מקומות זמין במאמר מזהי מקומות.

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

• languageCode

  השפה שבה יוצגו התוצאות.

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

• regionCode

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

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