לשיטות של Geocoding API v4 מוגדרת כברירת מחדל מכסה של 25 שאילתות לשנייה (QPS). מידע על בקשה להגדלת המכסה זמין במאמר איך רואים ומנהלים את המכסות. צריך לבחור באפשרות Geocoding API כשירות.

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

מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

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

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

בקשה להמרת קואורדינטות לכתובות (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, מכיל את ה-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), המרת כתובות לקואורדינטות (forward 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"
    },
    ...
  ]
}
```
פרטים נוספים מופיעים במאמר בנושא בחירת שדות להחזרה.

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

היפוך המיקום הגאוגרפי של המיקום קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

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

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

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

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

location

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

languageCode

regionCode

רמת פירוט

סוגים

FieldMask

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