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

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

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

בקשות להמרת כתובות של מקומות לקואורדינטות (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 כדי לשלוח בקשה

גרסה 4 של Geocoding API תומכת ב-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 שמייצג את המקום שתואם למזהה המקום.

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

1. ‫GeocodeResult.types: המערך הזה מציין את הסוגים הכלליים של התוצאה. הערכים האפשריים נלקחים מסוגי המקומות שבהם משתמש Places API. מידע נוסף זמין במאמר טבלאות א' וב' של סוגי מקומות.
2. ‫GeocodeResult.addressComponents[].types: לכל רכיב של הכתובת יש מערך types שמציין את הסוג של החלק הספציפי הזה בכתובת. הערכים האלה נלקחים מהטבלה סוגי כתובות וסוגי רכיבי כתובת שמשמשת את 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

  יוצרים מסכת שדה תגובה כדי לציין את השדות שיוחזרו בתגובה. מעבירים את מסכת השדות של התגובה ל-method באמצעות הפרמטר של כתובת ה-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"
  }

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