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

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

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

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

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

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

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

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

• languageCode

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

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

• regionCode

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

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