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

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

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

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

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

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

קוד האזור כערך של קוד CLDR בן שני תווים. אין ערך ברירת מחדל. רוב קודי CLDR זהים לקודי ISO 3166-1.
כשמבצעים גיאוקוד של כתובת, העברת גיאוקוד, הפרמטר הזה יכול להשפיע על התוצאות מהשירות לאזור שצוין, אבל לא להגביל אותן באופן מלא. כשמבצעים קידוד גיאוגרפי של מיקום או מקום, המרת קואורדינטות לכתובות (reverse 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`	מסלול בעל שם (למשל 'כביש 6').
`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`	נקודת עניין בעלת שם. בדרך כלל, 'נקודות העניין' האלה הן ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו 'בניין האמפייר סטייט' או 'מגדל אייפל'.

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