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

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

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

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

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

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

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

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

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

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

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

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

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

https://geocode.googleapis.com/v4beta/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/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

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

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

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

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

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

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

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

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

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

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

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

https://geocode.googleapis.com/v4beta/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 ‫— לשימוש עם כל נקודות הקצה של Geocoding API.
  • https://www.googleapis.com/auth/maps-platform.geocode.address ‫— לשימוש רק עם GeocodeAddress להמרת קואורדינטות לכתובות (geocoding).

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

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

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

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

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

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

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

הטיה של מיקום

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

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

https://geocode.googleapis.com/v4beta/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/v4beta/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/v4beta/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"
      ]
    },
    ...
  ]
}

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

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