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

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

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

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

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

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

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

• languageCode

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

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

• regionCode

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

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

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