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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• השדה plusCode, מסוג PlusCode, מכיל את ה-Plus Code שהכי קרוב לקו הרוחב ולקו האורך בבקשה. בנוסף, כל רכיב results במערך מכיל קוד פלוס. המרחק בין ה-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), המרת כתובות לקואורדינטות קדימה, הפרמטר הזה יכול להשפיע על התוצאות מהשירות, אבל לא להגביל אותן באופן מלא לאזור שצוין. כשממירים כתובת לקואורדינטות (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"
      },
      ...
    ]
  }

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