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