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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 תומך בהיקפים הבאים לשימוש עם המרת קואורדינטות לכתובות:

• https://www.googleapis.com/auth/maps-platform.geocode — משתמשים בכל השיטות של 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)

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

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

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

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

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

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

• regionCode

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

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

• סוגים

  סוג כתובת אחד או יותר, שצוינו כפרמטרים נפרדים של שאילתה. הערכים האפשריים נלקחים מהטבלה סוגי כתובות וסוגי רכיבים של כתובות בדף Place Types (New). אם מציינים כמה פרמטרים של 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

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

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