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

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

המרת כתובת לקואורדינטות

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

גיאו-קידוד מתרגם כתובת למיקום במפה. כשמבצעים גיאו-קידוד של כתובת, התגובה מכילה את:

מזהה המקום של המיקום
קואורדינטות של קו הרוחב וקו האורך של המיקום
Plus Code של המיקום
פרטי כתובת מורחבים

בקשה להמרת כתובות לקואורדינטות

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

https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING

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

https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS

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

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

העברת מחרוזת של כתובת לא מובנית

כתובת לא מובנית היא כתובת בפורמט של מחרוזת או של OLC. המרת כתובות לקואורדינטות לא פותרת קואורדינטות של קו רוחב וקו אורך, או מחרוזות לא מובנות אחרות שלא מייצגות כתובת או קוד OLC. בקשות שמשתמשות במחרוזות כאלה לא נתמכות, ויכול להיות שהן יובילו לתגובות שגיאה או להתנהגות לא מוגדרת. דוגמאות לשאילתות לא נתמכות:

סוג השאילתה	דוגמה
קואורדינטות של קו רוחב וקו אורך. במקום זאת, צריך להשתמש בהמרת קואורדינטות לכתובות (reverse geocoding).	‎"37.422131,-122.084801"‎
יותר מדי מושגים או אילוצים, כמו שמות של כמה מקומות, כבישים או ערים בשאילתה אחת	"Market Street San Francisco San Jose Airport"
רכיבים של כתובת למשלוח דואר שלא מיוצגים במפות Google	"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco"
שמות של עסקים, רשתות או קטגוריות בשילוב עם מיקומים שבהם הישויות האלה לא זמינות	‫"Tesco near Dallas, Texas"
שאילתות דו-משמעיות עם כמה פרשנויות	"Charger drop-off"
שמות היסטוריים שכבר לא נמצאים בשימוש	"Middlesex United Kingdom"
רכיבים או כוונות לא גיאוספציאליים	"כמה סירות יש בנמל ונטורה?"
שמות לא רשמיים או שמות מותאמים אישית	"The Jenga" "The Helter Skelter"

לדוגמה, הכתובת הבאה עוברת את הקידוד של מחרוזת הכתובת ב-URL ‏ "1600 Amphitheatre Parkway, Mountain View, CA":

https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

שימו לב שהתו '+' בכתובת ה-URL מומר לרווח.

אפשר גם לשלוח את הבקשה באמצעות פקודת curl:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

כתובות יכולות להכיל סוגים רבים של תווים מיוחדים. לדוגמה, "/" כמו בכתובת "7/1 King St, Concord West". מבצעים קידוד URL ל-'/' בתור %2F:

https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

דוגמה נפוצה נוספת היא התו '#', כמו בכתובת "9500 W Bryn Mawr Ave #650, Rosemont". צריך לבצע קידוד URL לסימן '#' כ-%2FE:

https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

בדוגמה הבאה, מחרוזת כתובת לא מובנית מוגדרת כקוד פלוס 849VCWC8+R4. חשוב לוודא שקידדתם את התו '+' בכתובת ה-URL כ-%2B:

https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY

העברת כתובת מובנית

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

לדוגמה, כדי לציין רק את המיקוד של הכתובת שבה אתם משתמשים PostalAddress.postalCode:

https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY

כדי לציין כמה רכיבי כתובת, למשל רכיבי כתובת שנתפסים בטופס HTML, משתמשים בכמה פרמטרים של שאילתה:

https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

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

‫Geocoding API v4 תומך ב-OAuth 2.0 לאימות. כדי להשתמש ב-OAuth עם Geocoding API, צריך להקצות לטוקן OAuth את ההיקף הנכון. ‫Geocoding API תומך בהיקפים הבאים לשימוש בקידוד גאוגרפי קדימה:

https://www.googleapis.com/auth/maps-platform.geocode ‫— לשימוש בכל ה-methods של Geocoding API.
https://www.googleapis.com/auth/maps-platform.geocode.address ‫— אפשר להשתמש רק ב-GeocodeAddress לגיאו-קידוד קדימה.

בנוסף, אפשר להשתמש בהיקף הכללי https://www.googleapis.com/auth/cloud-platform לכל ה-methods של Geocoding API. ההיקף הזה שימושי במהלך הפיתוח, אבל לא במהלך הייצור, כי זה היקף כללי שמאפשר גישה לכל השיטות.

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

תגובה של המרת כתובות לקואורדינטות

גיאו-קידוד מחזיר אובייקט GeocodeAddressResponse שמכיל את מערך results של אובייקטים GeocodeResult. כל אובייקט GeocodeResult מייצג מקום יחיד.

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

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

אובייקט ה-JSON המלא הוא בפורמט:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

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

‫address — כתובת או Plus Code שרוצים להמיר לקואורדינטות. הערה: המרת כתובת לקואורדינטות לא פותרת קואורדינטות של קו רוחב וקו אורך, או מחרוזות לא מובנות אחרות שלא מייצגות כתובת או קוד פלוס. פרטים נוספים ודוגמאות לשאילתות לא נתמכות זמינים במאמר העברת מחרוזת כתובת לא מובנית. צריך לציין כתובות בהתאם לפורמט שבו משתמש שירות הדואר הלאומי של המדינה הרלוונטית. מומלץ להימנע משימוש ברכיבי כתובת נוספים כמו שמות עסקים ומספרי יחידות, סוויטות או קומות. צריך להפריד בין רכיבי כתובת הרחוב ברווחים, ולקודד אותם בקידוד URL ל-%20. לדוגמה, כדי להעביר את הכתובת '24 Sussex Drive Ottawa ON' צריך להשתמש בפורמט הבא:
```
24%20Sussex%20Drive%20Ottawa%20ON
```
מעצבים את קודי ה-Plus Codes כמו בדוגמה הבאה. סימני פלוס מקודדים בכתובת URL כ-%2B ורווחים מקודדים בכתובת URL כ-%20:
- קוד גלובלי הוא קידומת אזור בת 4 תווים וקוד מקומי בן 6 תווים או יותר. לדוגמה, הקידוד של '849VCWC8+R9' הוא 849VCWC8%2BR9.
- קוד מורכב הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש. לדוגמה, הקידוד של 'CWC8+R9 Mountain View, CA, USA' הוא CWC8%2BR9%20Mountain%20View%20CA%20USA.

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

locationBias

מציין אזור לחיפוש בתור Viewport. המיקום הזה משמש כהטיה, כלומר יכול להיות שיוחזרו תוצאות שמסביב למיקום שצוין, כולל תוצאות שנמצאות קרוב לאזור אבל מחוצה לו.

הערה: אפשר לבטל את הפרמטר locationBias אם הכתובת המבוקשת מכילה מיקום מפורש כמו Barcelona, Spain. במקרה כזה, המערכת מתעלמת מהמדיניות locationBias.

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

אזור התצוגה נחשב לאזור סגור, כלומר הוא כולל את הגבול שלו. הגבולות של קו הרוחב צריכים להיות בין 90- ל-90 מעלות כולל, והגבולות של קו האורך צריכים להיות בין 180- ל-180 מעלות כולל:
- אם low = high, אזור התצוגה מורכב מהנקודה היחידה הזו.
- אם low.longitude > high.longitude, טווח קווי האורך הפוך (אזור התצוגה חוצה את קו האורך 180 מעלות).
- אם low.longitude = ‎-180 מעלות ו-high.longitude = ‎180 מעלות, אז אזור התצוגה כולל את כל קווי האורך.
- אם low.longitude = 180 מעלות ו-high.longitude = ‎-180 מעלות, טווח קווי האורך ריק.
- אם low.latitude > high.latitude, טווח קווי הרוחב ריק.
חובה למלא את שני הערכים, והתיבה שמייצגים לא יכולה להיות ריקה. אם אזור התצוגה ריק, תופיע שגיאה.

לדוגמה, מחרוזת השאילתה הזו מגדירה אזור תצוגה שמקיף באופן מלא את העיר ניו יורק:
```
?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018
```
languageCode

השפה שבה יוחזרו התוצאות.
- כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
- אם לא מציינים את הערך languageCode, ברירת המחדל של ה-API היא en. אם מציינים קוד שפה לא תקין, ה-API מחזיר שגיאה מסוג INVALID_ARGUMENT.
- ה-API עושה כמיטב יכולתו כדי לספק כתובת רחוב שניתן לקרוא אותה גם על ידי המשתמש וגם על ידי תושבים מקומיים. כדי להשיג את המטרה הזו, היא מחזירה כתובות רחוב בשפה המקומית, בתעתיק לכתב שניתן לקריאה על ידי המשתמש אם יש צורך בכך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מתוך הרכיב הראשון.
- אם שם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שממשק ה-API בוחר להחזיר, ועל הסדר שבו התוצאות מוחזרות. הגיאוקודר מפרש קיצורים בצורה שונה בהתאם לשפה, כמו קיצורים לסוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת.
regionCode

קוד האזור כערך קוד CLDR באורך שני תווים. אין ערך ברירת מחדל. רוב הקודים של CLDR זהים לקודים של ISO 3166-1.
כשמבצעים המרה של כתובת לקואורדינטות (geocoding), המרת כתובות לקואורדינטות קדימה, הפרמטר הזה יכול להשפיע על התוצאות מהשירות, אבל לא להגביל אותן באופן מלא לאזור שצוין. כשממירים כתובת לקואורדינטות (geocoding) של מיקום או של מקום, המרת קואורדינטות לכתובות (reverse geocoding) או המרת קואורדינטות לכתובות של מקומות, אפשר להשתמש בפרמטר הזה כדי לעצב את הכתובת. בכל המקרים, הפרמטר הזה יכול להשפיע על התוצאות בהתאם לדין החל.
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/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
```
התגובה היא:
```
{
  "results": [
    {
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc"
    }
  ]
}
```
פרטים נוספים מופיעים במאמר בנושא בחירת שדות להחזרה.

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

הטיה של מיקום

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

לדוגמה, בקשה לגיאו-קידוד של הכתובת "Washington" יכולה להחזיר תוצאות עבור וושינגטון הבירה ועבור מדינת וושינגטון בארה"ב:

https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY

התשובה היא בפורמט:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

עם זאת, אם מוסיפים פרמטר locationBias שמגדיר תיבת תוחמת סביב החלק הצפון-מזרחי של ארה"ב, הגיאוקוד מחזיר רק את העיר וושינגטון:

https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

תעדוף אזורי

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

אין ערך ברירת מחדל ל-regionCode. לדוגמה, קידוד גיאוגרפי של Toledo מחזיר תוצאות גם בארה"ב וגם בספרד:

https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY

תשובה:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

בקשת גיאו-קידוד ל-Toledo‏ (regionCode=es ספרד) מחזירה רק תוצאות מספרד:

https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY