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

דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://geocode.googleapis.com/v4beta/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 ‫— לשימוש עם כל נקודות הקצה של 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 שמייצג את המקום.

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

הערה: ה-API לא תמיד מחזיר קודי פלוס.

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

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

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

אם מציינים גם את types וגם את granularity, ה-API מחזיר רק את התוצאות שתואמות לשניהם. לדוגמה:
```
https://geocode.googleapis.com/v4beta/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/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

יש תמיכה בערכים הבאים:

סוגי כתובות וסוגי רכיבי כתובות

מערך types בגוף GeocodeResult בתגובה מציין את סוג הכתובת. דוגמאות לסוגי כתובות כוללות כתובת רחוב, מדינה או ישות פוליטית. המערך types בשדה AddressComponents של גוף GeocodeResult מציין את הסוג של כל חלק בכתובת. לדוגמה, מספר בית או מדינה.

יכולים להיות כמה סוגים של כתובות. אפשר להתייחס לסוגים האלה כאל 'תגים'. לדוגמה, ערים רבות מתויגות בסוגים political ו-locality.

הסוגים הבאים נתמכים ומוחזרים במערכים של סוג הכתובת וסוג רכיב הכתובת:

סוג כתובת	תיאור
`street_address`	כתובת רחוב מדויקת.
`route`	מסלול עם שם (לדוגמה, כביש 101 בארה"ב).
`intersection`	צומת גדול, בדרך כלל של שני כבישים ראשיים.
`political`	ישות פוליטית. בדרך כלל, הסוג הזה מציין מצולע של איזושהי רשות אזרחית.
`country`	הישות הפוליטית הלאומית, ובדרך כלל זהו הסוג ברמה הגבוהה ביותר שמוחזר על ידי הגיאוקודר.
`administrative_area_level_1`	חלוקה מנהלית מדרגה ראשונה מתחת לרמה הארצית. בארצות הברית, הרמות האדמיניסטרטיביות האלה הן מדינות. לא בכל הארצות יש רמות אדמיניסטרטיביות כאלה. ברוב המקרים, השמות הקצרים `administrative_area_level_1` יהיו דומים לחלוקות המשנה של ISO 3166-2 ולרשימות אחרות שמופצות באופן נרחב. עם זאת, אין בכך ערובה, כי תוצאות הגיאו-קידוד שלנו מבוססות על מגוון אותות ונתוני מיקום.
`administrative_area_level_2`	חלוקה מנהלית מדרגה שנייה מתחת לרמה הארצית. בארצות הברית, הרמות האדמיניסטרטיביות האלה הן מחוזות. לא בכל הארצות יש רמות אדמיניסטרטיביות כאלה.
`administrative_area_level_3`	חלוקה מנהלית מדרגה שלישית מתחת לרמה הארצית. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל הארצות יש רמות אדמיניסטרטיביות כאלה.
`administrative_area_level_4`	חלוקה מנהלית מדרגה רביעית מתחת לרמה הארצית. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל הארצות יש רמות אדמיניסטרטיביות כאלה.
`administrative_area_level_5`	חלוקה מנהלית מדרגה חמישית מתחת לרמה הארצית. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל הארצות יש רמות אדמיניסטרטיביות כאלה.
`administrative_area_level_6`	חלוקה מנהלית מדרגה שישית מתחת לרמה הארצית. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל הארצות יש רמות אדמיניסטרטיביות כאלה.
`administrative_area_level_7`	חלוקה מנהלית מדרגה שביעית מתחת לרמה הארצית. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל הארצות יש רמות אדמיניסטרטיביות כאלה.
`colloquial_area`	שם חלופי שמשמש בדרך כלל להתייחסות לישות.
`locality`	ישות פוליטית של עיר או עיירה מאוגדת.
`sublocality`	חלוקה מנהלית מדרגה ראשונה מתחת לרמה המקומית. יכול להיות שחלק מהמיקומים יקבלו אחד מהסוגים הנוספים: `sublocality_level_1` עד `sublocality_level_5`. כל רמה של מיקום משני היא ישות אזרחית. מספרים גדולים יותר מציינים אזור גיאוגרפי קטן יותר.
`neighborhood`	שכונה עם שם.
`premise`	מיקום עם שם, בדרך כלל בניין או קבוצת בניינים עם שם משותף.
`subpremise`	ישות שאפשר להקצות לה כתובת מתחת לרמת המקום, כמו דירה, יחידה או סוויטה.
`plus_code`	הפניה למיקום מקודד, שנגזרת מקו הרוחב וקו האורך. אפשר להשתמש ב-Plus Codes במקום בכתובות רחוב במקומות שבהם אין כתובות כאלה (במקומות שבהם הבניינים לא ממוספרים או שהרחובות לא נקראים בשם). פרטים נוספים זמינים בכתובת https://plus.codes.
`postal_code`	מיקוד שמשמש לכתובת למשלוח דואר בתוך המדינה.
`natural_feature`	מאפיין טבעי בולט.
`airport`	שדה תעופה.
`park`	פארק עם שם.
`point_of_interest`	נקודת עניין עם שם. בדרך כלל, ה-POI האלה הם ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו 'אמפייר סטייט בילדינג' או 'מגדל אייפל'.

רשימה ריקה של סוגים מציינת שאין סוגים ידועים לרכיב הכתובת הספציפי (לדוגמה, Lieu-dit בצרפת).