היפוך המיקום הגאוגרפי של המיקום

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

כשמבצעים המרת קואורדינטות לכתובות של מיקום, התשובה מכילה את:

• מזהה המקום של הכתובת
• Plus Codes של הכתובת
• פרטי הכתובת

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

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

בקשה לגיאו-קידוד הפוך היא בקשת HTTP GET. אפשר לציין את המיקום כמחרוזת לא מובנית:

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

או כקבוצה מובנית של קואורדינטות של קו רוחב וקו אורך שמיוצגות על ידי פרמטרים של שאילתה:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

בדרך כלל משתמשים בפורמט המובנה כשמעבדים רכיבי מיקום שנאספו בטופס HTML.

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

העברת מחרוזת מיקום לא מובנית

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

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?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/location/37.4225508,-122.0846338"

העברת מיקום מובנה

מציינים את המיקום המובנה באמצעות פרמטר השאילתה location, מסוג LatLng. אובייקט LatLng מאפשר לציין את קו הרוחב וקו האורך כפרמטרים נפרדים של שאילתה:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

שימוש ב-OAuth כדי לשלוח בקשה

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

• https://www.googleapis.com/auth/maps-platform.geocode ‫— לשימוש בכל ה-methods של Geocoding API.
• https://www.googleapis.com/auth/maps-platform.geocode.location ‫— אפשר להשתמש רק עם GeocodeLocation להמרת קואורדינטות לכתובות (reverse geocoding).

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

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

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

המרת קואורדינטות לכתובות מחזירה אובייקט GeocodeLocationResponse שמכיל:

• מערך results של אובייקטים מסוג GeocodeResult שמייצגים את המקום.

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

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

  הגיאוקודר ההפוך מחזיר יותר מתוצאה אחת במערך results. התוצאות הן לא רק כתובות למשלוח דואר, אלא כל דרך לתת שם למיקום גיאוגרפי. לדוגמה, כשמבצעים גיאו-קידוד של נקודה בעיר שיקגו, יכול להיות שהנקודה המקודדת תצוין ככתובת רחוב, כעיר (שיקגו), כמדינה (אילינוי) או כמדינה (ארצות הברית). כל הערכים האלה הם 'כתובות' עבור הגיאוקודר. הגיאוקודר ההפוך מחזיר כל אחד מהסוגים האלה כתוצאות תקינות.

• השדה plusCode, מסוג PlusCode, מכיל את קוד ה-OLC שהכי קרוב לקו הרוחב ולקו האורך שצוינו בבקשה. בנוסף, כל רכיב במערך results מכיל קוד OLC. המרחק בין קוד ה-OLC המפוענח לבין נקודת הבקשה הוא פחות מ-10 מטרים.

  הערה: ה-API לא תמיד מחזיר Plus Codes.

אובייקט ה-JSON המלא הוא מהצורה:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

פרמטרים נדרשים

• location

  קואורדינטות של קו רוחב וקו אורך שמציינות את המיקום שבו רוצים לקבל את הכתובת הקרובה ביותר שניתנת לקריאה על ידי בני אדם.

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

• languageCode

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

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

• regionCode

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

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

• רמת פירוט

  רמת פירוט אחת או יותר של מיקום, שצוינו כפרמטרים נפרדים של שאילתה, כפי שמוגדר על ידי Granularity. אם מציינים כמה פרמטרים של granularity, ה-API מחזיר את כל הכתובות שתואמות לכל אחת מהרמות.

  הפרמטר granularity לא מגביל את החיפוש לרמות הפירוט של המיקום שצוינו. במקום זאת, granularity פועל כמסנן אחרי החיפוש. ה-API מאחזר את כל התוצאות של location שצוין, ואז מסנן את התוצאות שלא תואמות לגרנולריות של המיקום שצוין.

  אם מציינים גם את types וגם את granularity, ה-API מחזיר רק את התוצאות שתואמות לשניהם. לדוגמה:

  https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

• סוגים

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

  הפרמטר types לא מגביל את החיפוש לסוגי הכתובות שצוינו. במקום זאת, types פועל כמסנן אחרי החיפוש. ה-API מאחזר את כל התוצאות למיקום שצוין, ואז מסיר את התוצאות שלא תואמות לסוגי הכתובות שצוינו.

  אם מציינים גם את types וגם את granularity, ה-API מחזיר רק את התוצאות שתואמות לשניהם. לדוגמה:

  https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

• FieldMask

  יוצרים מסכת שדות תגובה כדי לציין את השדות שיוחזרו בתגובה. מעבירים את מסכת שדות התגובה לשיטה באמצעות פרמטר כתובת ה-URL ‏$fields או fields, או באמצעות כותרת ה-HTTP ‏X-Goog-FieldMask. לדוגמה, הבקשה שלמטה תחזיר רק את השדות placeID של התגובה.

  curl -X GET -H 'Content-Type: application/json' \
  -H 'X-Goog-FieldMask: results.placeId' \
  -H "X-Goog-Api-Key: API_KEY" \
  "https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
  

  התשובה היא:

  {
    "results": [
      {
        "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
      },
      {
        "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
      },
      {
        "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
      },
      {
        "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
      },
      ...
    ]
  }

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