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

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

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

גרסה 4 של Geocoding API תומכת ב-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 לכל השיטות של Geocoding API. ההיקף הזה שימושי במהלך הפיתוח, אבל לא בייצור, כי הוא היקף כללי שמאפשר גישה לכל השיטות.

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

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

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

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

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

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

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

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

• regionCode

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

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

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

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