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

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

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

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

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

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

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

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

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

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 — משתמשים בכל השיטות של 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)

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

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

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

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

  • regionCode

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

    כשממירים כתובת לקואורדינטות (forward geocoding), הפרמטר הזה יכול להשפיע על התוצאות מהשירות לאזור שצוין, אבל לא להגביל אותן באופן מלא. כשממירים מיקום או מקום לקואורדינטות (geocoding), ממירים קואורדינטות לכתובות (reverse geocoding) או ממירים מקום לקואורדינטות (place 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"
}

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