בקשה
הפורמט של בקשה ל-Geocoding API הוא:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
כאשר outputFormat יכול להיות אחד מהערכים הבאים:
json(מומלץ) מציין פלט ב-JavaScript Object Notation (JSON); אוxmlמציין פלט בפורמט XML
נדרש HTTPS.
חלק מהפרמטרים נדרשים וחלקם אופציונליים. כנהוג בכתובות URL, הפרמטרים מופרדים באמצעות התו אמפרסנד (&).
בהמשך הדף מתוארים המרת קואורדינטות והמרת קואורדינטות לכתובות (reverse geocoding) בנפרד, כי יש פרמטרים שונים לכל סוג של בקשה.
פרמטרים של המרת כתובות לקואורדינטות (חיפוש קו אורך/רוחב)
פרמטרים נדרשים בבקשת גיאוקוד:
address– רחוב או Plus Code שרוצים להמיר לקואורדינטות. יש לציין את הכתובות בהתאם לפורמט שבו נעשה שימוש בשירות הדואר הלאומי במדינה הרלוונטית. מומלץ להימנע מרכיבים נוספים בכתובת, כמו שמות של עסקים ומספרי יחידות, סוויטות או קומות. יש להפריד בין הרכיבים של הרחוב באמצעות רווחים (מוצגים כאן כתובת URL עם תווי בריחה ל-%20):address=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).
--OR--
components— מסנן רכיבים עם רכיבים שמפרידים ביניהם צינור (|). אפשר להשתמש במסנן הרכיבים גם כפרמטר אופציונלי אם מצייניםaddress. כל אלמנט במסנן הרכיבים מורכב מצמדcomponent:value, והוא מגביל באופן מלא את התוצאות מהמקודם הגיאוגרפי. בהמשך מפורט מידע נוסף על סינון רכיבים.- קוד גלובלי הוא קידומת אזור בת 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9 הוא
key– מפתח ה-API של האפליקציה. המפתח הזה מזהה את האפליקציה שלכם לצורכי ניהול מכסות. איך מקבלים מפתח
בשאלות הנפוצות מפורטות הנחיות נוספות.
פרמטרים אופציונליים בבקשת גיאוקוד:
bounds— תיבת המגבלה של אזור התצוגה שבה מתבצעת הטיה של תוצאות הגיאוקוד כך שיוצגו באופן בולט יותר. הפרמטר הזה ישפיע רק על התוצאות מהמקודד הגיאוגרפי, ולא יגביל אותן לחלוטין. (מידע נוסף זמין בקטע הטיה של חלון התצוגה בהמשך).language– השפה שבה יוצגו התוצאות.- כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא תהיה מקיפה.
- אם לא מציינים את
language, מקודד המיקום מנסה להשתמש בשפה המועדפת כפי שצוינה בכותרתAccept-Language, או בשפה המקומית של הדומיין שממנו נשלחה הבקשה. - השירות למיפוי גיאוגרפי עושה כמיטב יכולתו כדי לספק כתובת רחוב שאפשר לקרוא גם למשתמש וגם לאנשים מקומיים. כדי להשיג את המטרה הזו, המערכת מחזירה כתובות רחוב בשפה המקומית, עם תעתיק שלהן לכתב שאפשר לקרוא על ידי המשתמש, אם יש צורך, בהתאם לשפה המועדפת. כל הכתובות האחרות יחזרו בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מהרכיב הראשון.
- אם שם לא זמין בשפה המועדפת, המערכת למיפוי גיאוגרפי משתמשת בהתאמה הקרובה ביותר.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שה-API בוחר להחזיר ועל הסדר שבו הן מוחזרות. המערכת למיפוי גיאוגרפי מפענחת קיצורים באופן שונה בהתאם לשפה, למשל קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, utca ו-tér הם שמות נרדפים ל'רחוב' ול'כיכר' בהונגרית.
region– קוד האזור, שמצוין כערך בן שני תווים של דומיין ברמה עליונה עם קוד מדינה (ccTLD). הפרמטר הזה ישפיע רק על התוצאות מהמקודד הגיאוגרפי, ולא יגביל אותן לחלוטין. (למידע נוסף, ראו הטיה לפי אזור בהמשך). הפרמטר יכול להשפיע גם על התוצאות בהתאם לדין החל.components– מסנן רכיבים עם רכיבים שמפרידים ביניהם צינור (|). מסנן הרכיבים נדרש אם הבקשה לא כוללתaddress. כל אלמנט במסנן הרכיבים מורכב מצמדcomponent:value, והוא מגביל באופן מלא את התוצאות מהמקודם הגיאוגרפי. בהמשך מפורט מידע נוסף על סינון רכיבים.extra_computations– אפשר להשתמש בפרמטר הזה כדי לציין את התכונות הנוספות הבאות בתגובה:ADDRESS_DESCRIPTORS– פרטים נוספים זמינים במאמר מתארי כתובות.BUILDING_AND_ENTRANCES– פרטים נוספים זמינים במאמר כניסות וקווי מתאר של מבנים.
extra_computationsבבקשה לכל תכונה, לדוגמה:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
תשובות
התשובות של השירות לגיאוקוד מוחזר בפורמט שמצוין בדגל output בתוך בקשת כתובת ה-URL, או בפורמט JSON כברירת מחדל.
בדוגמה הזו, Geocoding API מבקש תגובה מסוג json לשאילתה לגבי הכתובת 1600 Amphitheatre Parkway, Mountain View, CA.
הבקשה הזו מדגימה את השימוש בדגל output ב-JSON:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
בבקשה הזו מוצג השימוש בדגל output ב-XML:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
בוחרים את הכרטיסיות הבאות כדי להציג את תגובות ה-JSON וה-XML לדוגמה.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
שימו לב שתגובת ה-JSON מכילה שני רכיבי root:
- השדה
"status"מכיל מטא-נתונים על הבקשה. קודי סטטוס מפורטים בהמשך. - השדה
"results"מכיל מערך של פרטי כתובות שהותאמו למיקום גיאוגרפי ופרטי גיאומטריה.
בדרך כלל, מערכת המיפוי מחזירה רק רשומה אחת במערך "results" לחיפוש כתובות, אבל יכול להיות שהיא תחזיר כמה תוצאות אם שאילתות הכתובות לא ברורות.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
שימו לב שתגובת ה-XML מורכבת מרכיב <GeocodeResponse> יחיד ושני רכיבים ברמה העליונה:
- השדה
<status>מכיל מטא-נתונים על הבקשה. קודי סטטוס - אפס או יותר רכיבי
<result>, שכל אחד מהם מכיל קבוצה אחת של נתוני כתובת ונתוני גיאומטריה שעבר גיאוקוד.
תגובת ה-XML ארוכה בהרבה מתגובת ה-JSON. לכן, מומלץ להשתמש ב-json כדגל הפלט המועדף, אלא אם השירות דורש את xml מסיבה כלשהי.
בנוסף, עיבוד של עצי XML דורש קצת זהירות, כדי שתוכלו להפנות לרכיבים ולצומתים המתאימים. במאמר ניתוח XML באמצעות XPath מפורטות כמה תבניות תכנון מומלצות לעיבוד פלט.
- תוצאות ה-XML עטופות ברכיב
<GeocodeResponse>ברמה הבסיסית. - ב-JSON, רשומות עם כמה רכיבים מסומנות במערכים ברבים (
types), ואילו ב-XML הן מסומנות באמצעות כמה רכיבים ביחיד (<type>). - רכיבים ריקים מסומנים במערכים ריקים ב-JSON, אבל בהיעדר רכיב כזה ב-XML. לדוגמה, תגובה שלא מניבה תוצאות תחזיר מערך
resultsריק ב-JSON, אבל לא תחזיר רכיבי<result>ב-XML.
קודי סטטוס
השדה "status" באובייקט התשובה של הגיאוקוד מכיל את סטטוס הבקשה, ויכול להכיל מידע על ניפוי באגים שיעזור לכם למצוא את הסיבה לכך שהגיאוקוד לא פועל. השדה "status" יכול להכיל את הערכים הבאים:
- הערך
"OK"מציין שלא אירעו שגיאות, שהכתובת נותחה בהצלחה ושהוחזר לפחות קואורדינטה אחת. - הערך
"ZERO_RESULTS"מציין שהפעלת ה-geocode הסתיימה בהצלחה, אבל לא הוחזרו תוצאות. מצב כזה יכול לקרות אם הועברו למקודם הגיאוגרפית נתוניaddressלא קיימים. - הערך
OVER_DAILY_LIMITמציין אחת מהאפשרויות הבאות:- מפתח ה-API חסר או לא תקין.
- החיוב לא הופעל בחשבון שלך.
- חרגתם ממכסת השימוש שהגדרתם לעצמכם.
- אמצעי התשלום שצוין כבר לא תקף (לדוגמה, פג התוקף של כרטיס אשראי).
כאן מוסבר איך לפתור את הבעיה.
"OVER_QUERY_LIMIT"מציין שחרגתם מהמכסה."REQUEST_DENIED"מציין שהבקשה נדחתה.- בדרך כלל, הערך
"INVALID_REQUEST"מציין שהשאילתה (address,componentsאוlatlng) חסרה. - הערך
"UNKNOWN_ERROR"מציין שלא ניתן היה לעבד את הבקשה עקב שגיאה בשרת. יכול להיות שהבקשה תצליח אם תנסה שוב.
הודעות שגיאה
אם קוד הסטטוס שמוחזר על ידי המקודד הגיאוגרפי שונה מ-OK, יכול להיות שיופיע שדה error_message נוסף באובייקט התגובה של המקודד הגיאוגרפי. השדה הזה מכיל מידע מפורט יותר על הסיבות לקוד הסטטוס הנתון.
תוצאות
כשהמקודד הגיאוגרפי מחזיר תוצאות, הוא ממוקם אותן במערך results (JSON). גם אם המקודד הגיאוגרפי לא מחזיר תוצאות (למשל, אם הכתובת לא קיימת), הוא עדיין מחזיר מערך results ריק. (תשובות XML מורכבות מאפס או יותר רכיבי <result>).
תוצאה אופיינית מכילה את השדות הבאים:
- מערך
types[]מציין את הסוג של התוצאה שמוחזרת. המערך הזה מכיל קבוצה של אפס תגים או יותר שמזהים את סוג התכונה שמוחזרת בתוצאה. לדוגמה, כתובת גיאוגרפית של 'תל אביב' מחזירה את הערך 'locality', שמציין ש'תל אביב' היא עיר, וגם את הערך 'political', שמציין שהיא ישות פוליטית. יכול להיות שרכיבים יהיו עם מערך ריק של סוגי כתובות אם אין סוגי כתובות ידועים לרכיב הכתובת הזה. ה-API עשוי להוסיף ערכים חדשים של סוגים לפי הצורך. מידע נוסף זמין במאמר סוגי כתובות ורכיבי כתובות. formatted_addressהיא מחרוזת שמכילה את הכתובת של המיקום הזה, שקריאה לבני אדם.לרוב, הכתובת הזו זהה לכתובת למשלוח דואר. חשוב לדעת שבמדינות מסוימות, כמו בריטניה, אסור להפיץ כתובות דואר אמיתיות בגלל הגבלות רישוי.
הכתובת הפורמטית מורכבת באופן לוגי מרכיבי כתובת אחד או יותר. לדוגמה, הכתובת 111 8th Avenue, New York, NY מורכבת מהרכיבים הבאים: 111 (מספר הרחוב), 8th Avenue (הדרך), New York (העיר) ו-NY (המדינה בארה"ב).
אין לנתח את הכתובת בפורמט באופן פרוגרמטי. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכלולים בתשובת ה-API בנוסף לשדה הכתובת המעוצב.
address_components[]הוא מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.בדרך כלל, כל רכיב של כתובת מכיל את השדות הבאים:
types[]הוא מערך שמציין את הסוג של רכיב הכתובת. כאן אפשר לעיין ברשימת הסוגים הנתמכים.long_nameהוא תיאור הטקסט המלא או השם של רכיב הכתובת, כפי שהוחזר על ידי המקודד הגיאוגרפי.short_nameהוא שם מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של המדינה אלסקה יכול לכלול את הערךlong_nameשל 'אלסקה' ואת הערךshort_nameשל 'AK', לפי הקיצור הדו-אותי של המדינה.
שימו לב לעובדות הבאות לגבי המערך
address_components[]:- מערך הרכיבים של הכתובת עשוי להכיל יותר רכיבים מאשר
formatted_address. - המערך לא כולל בהכרח את כל הישות הפוליטיות שמכילות כתובת, מלבד אלה שכלולות ב-
formatted_address. כדי לאחזר את כל הישות הפוליטיות שמכילות כתובת ספציפית, צריך להשתמש בגיאוגקוד הפוך, ולהעביר את קו הרוחב/האורך של הכתובת כפרמטר לבקשה. - אין ערובה לכך שהפורמט של התשובה יישאר זהה בין הבקשות. באופן ספציפי, מספר הערכים של
address_componentsמשתנה בהתאם לכתובת המבוקשת, ויכול להשתנות עם הזמן לאותה כתובת. רכיב יכול לשנות את המיקום במערך. סוג הרכיב יכול להשתנות. יכול להיות שרכיב מסוים יהיה חסר בתגובה מאוחר יותר.
כדי לטפל במערך הרכיבים, צריך לנתח את התגובה ולבחור ערכים מתאימים באמצעות ביטויים. עיינו במדריך ל ניתוח תגובה.
postcode_localities[]הוא מערך שמציין עד 100 יישובים שמכילים מיקוד. השדה הזה מופיע רק אם התוצאה היא מיקוד שמכיל כמה מקומות.- השדה
geometryמכיל את המידע הבא:- השדה
locationמכיל את הערך של קו האורך וקו הרוחב המתואם למיקום גיאוגרפי. בשאילתות רגילות לחיפוש כתובות, השדה הזה הוא בדרך כלל החשוב ביותר. location_typeשומר נתונים נוספים על המיקום שצוין. בשלב הזה יש תמיכה בערכים הבאים:- הערך
"ROOFTOP"מציין שהתוצאה שהוחזרה היא קוד גיאוגרפי מדויק שיש לנו לגביו מידע על המיקום, עד לרמת הכתובת. - הערך
"RANGE_INTERPOLATED"מציין שהתוצאה שמוחזרת משקפת הערכה (בדרך כלל על דרך) שעבר תהליך אינטרפולציה בין שתי נקודות מדויקות (כמו צמתים). בדרך כלל, תוצאות אינטרפולציה מוחזרות כשאין קואורדינטות גיאוגרפיות של גגות עבור כתובת רחוב. - הערך
"GEOMETRIC_CENTER"מציין שהתוצאה שמוחזרת היא המרכז הגיאומטרי של תוצאה כמו קו מרובע (למשל, רחוב) או פוליגון (אזור). "APPROXIMATE"מציין שהתוצאה שהתקבלה היא משוערת.
- הערך
- השדה
viewportמכיל את אזור התצוגה המומלץ להצגת התוצאה שהתקבלה, שצוין בשני ערכים של קו הרוחב ואורך הגלובוס שמגדירים את הפינותsouthwestו-northeastשל תיבת הגבול של אזור התצוגה. בדרך כלל, חלון התצוגה משמש להגדרת המסגרת של התוצאה כשהיא מוצגת למשתמש. - המשתנה
bounds(אופציונלי) שומר את תיבת הגבול שיכולה להכיל את התוצאה המוחזרת במלואה. חשוב לזכור שהגבולות האלה עשויים שלא להתאים למסך המכוון המומלץ. (לדוגמה, סן פרנסיסקו כוללת את איי פרלון, ששייכים טכנית לעיר, אבל סביר להניח שלא כדאי להציג אותם בחלון התצוגה).
- השדה
-
plus_code(ראו Open Location Code וPlus Codes) הוא הפניה מקודדת למיקום, שמבוססת על קואורדינטות של קווי אורך ורוחב, שמייצגת אזור: 1/8000 מעלה על 1/8000 מעלה (כ-14 מ' על 14 מ' בקווי הרוחב) או קטן יותר. אפשר להשתמש ב-Plus Codes כתחליף לכתובות רחוב במקומות שבהם אין כתובות (למשל, מקומות שבהם אין מספרים לבניינים או שמות לרחובות). ה-API לא תמיד מחזיר קודי Plus.אם השירות מחזיר קוד Plus, הוא מוצג בפורמט של קוד גלובלי וקוד מורכב:
global_codeהוא קוד אזור בן 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9).compound_codeהוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9, Mountain View, CA, USA). אסור לנתח את התוכן הזה באופן פרוגרמטי.
-
הערך
partial_matchמציין שהמקודד הגיאוגרפי לא החזיר התאמה מדויקת לבקשה המקורית, אבל הוא הצליח להתאים חלק מהכתובת המבוקשת. מומלץ לבדוק את הבקשה המקורית כדי לראות אם יש בה שגיאות כתיב או כתובת חלקית.התאמות חלקיות מתרחשות לרוב בכתובות רחוב שלא קיימות ביישוב שציינתם בבקשה. יכול להיות שיתקבלו גם התאמות חלקיות כשבקשה תואמת לשני מיקומים או יותר באותה יישוב. לדוגמה, 'Hillpar St, Bristol, UK' תחזיר התאמה חלקית גם לרחוב Henry וגם לרחוב Henrietta. שימו לב שאם בקשה כוללת רכיב של כתובת עם שגיאת איות, שירות הגיאוקוד עשוי להציע כתובת חלופית. הצעות שתופעלו באופן הזה יסומנו גם כהתאמה חלקית.
place_idהוא מזהה ייחודי שאפשר להשתמש בו עם ממשקי Google API אחרים. לדוגמה, אפשר להשתמש ב-place_idבבקשה ל-Places API כדי לקבל פרטים על עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות של משתמשים ועוד. סקירה כללית על מזהי מקומות
סוגי כתובות וסוגי רכיבי כתובות
המערך types[] בתוצאה מציין את סוג הכתובת. דוגמאות לסוגי כתובות כוללות רחוב, מדינה או ישות פוליטית. יש גם מערך types[] ב-address_components[], שמציין את הסוג של כל חלק בכתובת. דוגמאות: מספר בית או מדינה. (בהמשך מופיעה רשימה מלאה של הסוגים). לכתובות יכולים להיות כמה סוגים. אפשר להתייחס לסוגי הפריטים האלה כ 'תגים'.
לדוגמה, ערים רבות מתויגות בתגים מסוג political ו-locality.
המערכת תומכת בסוגי המידע הבאים ומחזירה אותם על ידי המקודד הגיאוגרפי גם במערכים של סוגי הכתובות וגם במערכים של סוגי רכיבי הכתובות:
street_addressמציין כתובת רחוב מדויקת.routeמציין מסלול בעל שם (למשל 'US 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מציין נקודת עניין בעלת שם. בדרך כלל, 'נקודות העניין' האלה הן ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו 'בניין האמפייר סטייט' או 'מגדל אייפל'.
רשימה ריקה של סוגים מציינת שאין סוגים ידועים לרכיב הכתובת הספציפי, למשל Lieu-dit בצרפת.
בנוסף לרכיבים שלמעלה, רכיבי הכתובת עשויים לכלול את הסוגים שמפורטים כאן. הרשימה הזו חלקית בלבד ועומדת להשתנות.
floorמציין את הקומה בכתובת של מבנה.- הערך
establishmentבדרך כלל מציין מקום שעדיין לא סווג. landmarkמציין מקום קרוב שמשמש כנקודת עזרה לניווט.point_of_interestמציין נקודת עניין בעלת שם.parkingמציין חניון או מגרש חניה.post_boxמציין תיבת דואר ספציפית.postal_townמציין קיבוץ של אזורים גיאוגרפיים, כמוlocalityו-sublocality, שמשמשים לכתובות למשלוח דואר במדינות מסוימות.roomמציין את החדר בכתובת של בניין.street_numberמציין את מספר הרחוב המדויק.bus_station, train_stationו-transit_stationמציינים את המיקום של תחנת אוטובוס, רכבת או תחבורה ציבורית.
הטיה של אזור התצוגה
בבקשה להמרת כתובות לקואורדינטות (geocoding), אפשר להורות לשירות להעדיף תוצאות בתוך חלון תצוגה נתון (שמוצג כתיבת מלבנית). כדי לעשות זאת, מגדירים את הפרמטר bounds בכתובת ה-URL של הבקשה.
הפרמטר bounds מגדיר את קואורדינטות קו הרוחב/קו האורך של הפינות הדרום-מערבית והצפון-מזרחית של תיבת הגבול הזו, באמצעות צינור (|) כדי להפריד בין הקואורדינטות.
לדוגמה, כתובת גיאוגרפית של 'Washington' בדרך כלל מחזירה את המדינה Washington בארה"ב:
בקשה:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
תשובה:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
עם זאת, הוספת ארגומנט bounds שמגדיר תיבת מלבנית סביב החלק הצפון-מזרחי של ארה"ב מובילה לכך שהקוד הגיאוגרפית הזה יחזיר את העיר וושינגטון די. סי.:
בקשה:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
תשובה:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
הטיה לפי אזור
בבקשה לביצוע המרה של כתובת לקואורדינטות, אפשר להורות לשירות המרה של כתובת לקואורדינטות להחזיר תוצאות שמתמקדות באזור מסוים באמצעות הפרמטר region. הפרמטר הזה מקבל ארגומנטים של ccTLD (דומיין ברמה עליונה עם קוד מדינה) שמציינים את ההטיה לאזור. רוב הקודים של הדומיינים ברמה הלאומית זהים לקודי ISO 3166-1, מלבד כמה יוצאים מן הכלל. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא 'uk' (.co.uk), ואילו הקוד שלה לפי תקן ISO 3166-1 הוא 'gb' (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד').
תוצאות הגיאוקוד יכולות להיות מוטה בכל דומיין שבו אפליקציית מפות Google הראשית הושקה באופן רשמי. חשוב לזכור שהטיה רק מעדיפה תוצאות של דומיין ספציפי. אם יש תוצאות רלוונטיות יותר מחוץ לדומיין הזה, הן עשויות להיכלל.
לדוגמה, כתובת גיאוגרפית של 'טולדו' מחזירה את התוצאה הזו, כי דומיין ברירת המחדל של Geocoding API מוגדר לארצות הברית. בקשה:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
תשובה:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
בקשה ליצירת כתובת ממיקוד גיאוגרפי של 'Toledo' עם region=es (ספרד) תחזיר את העיר בספרד.
בקשה:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
תשובה:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
סינון רכיבים
בתשובה של Geocoding API, אפשר לקבל תוצאות של כתובות שמוגבלות לאזור ספציפי. אפשר לציין את ההגבלה באמצעות המסנן components. מסנן מורכב מרשימת צמדי component:value שמופרדים באמצעות צינור (|). ערכי המסנן תומכים באותן שיטות של תיקון שגיאות איות והתאמה חלקית כמו בשאילתות אחרות של יצירת כתובות. אם מערכת המיפוי הגיאוגרפית מוצאת התאמה חלקית למסנן רכיב, התגובה תכלול את השדה partial_match.
השדות של components שאפשר לסנן כוללים:
-
postal_codeתואם ל-postal_codeול-postal_code_prefix. countryתואם לשם מדינה או לקוד מדינה בן שתי אותיות לפי תקן ISO 3166-1. ה-API פועל בהתאם לתקן ISO להגדרת מדינות, והסינון פועל בצורה הטובה ביותר כשמשתמשים בקוד ה-ISO התואם של המדינה.
אפשר להשתמש ב-components הבא כדי להשפיע על התוצאות, אבל הוא לא יאכף:
routeתואם לשם הארוך או הקצר של נתיב.localityתואם לסוגיםlocalityו-sublocality.administrative_areaתואם לכל הרמות שלadministrative_area.
הערות לגבי סינון רכיבים:
- אין לחזור על מסנני הרכיבים האלה בבקשות, אחרת ה-API יחזיר את הערכים הבאים:
Invalid_request:country, postal_code,route - אם הבקשה מכילה מסנני רכיבים חוזרים, ה-API מעריך את המסננים האלה כ-AND ולא כ-OR.
- התוצאות תואמות למפות Google, שבהן לפעמים מופיעות תשובות
ZERO_RESULTSלא צפויות. שימוש בהשלמה האוטומטית למקומות יכול לספק תוצאות טובות יותר בתרחישי שימוש מסוימים. מידע נוסף זמין בשאלות הנפוצות האלה. - לכל רכיב של הכתובת, צריך לציין אותו בפרמטר
addressאו במסנןcomponents, אבל לא בשניהם. ציון אותם ערכים בשני השדות עלול לגרום ל-ZERO_RESULTS.
כתובת גיאוגרפית של 'High St, Hastings' עם components=country:GB
מחזירה תוצאה ב-Hastings שבאנגליה ולא ב-Hastings-On-Hudson בארה"ב.
בקשה:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
תשובה:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
בקשת גיאוקוד של היישוב 'סנטה קרוז' עם components=country:ES
מחזירה את סנטה קרוז דה טנריף באיים הקנריים, ספרד.
בקשה:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
תשובה:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
סינון רכיבים מחזיר תשובה מסוג ZERO_RESULTS רק אם מספקים מסננים שמחריגים זה את זה.
בקשה:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
תשובה:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
אפשר ליצור שאילתות תקינות בלי פרמטר הכתובת, באמצעות המסנן components. (כשמבצעים גיאוקוד של כתובת מלאה, צריך להוסיף את הפרמטר address אם הבקשה מכילה את השמות והמספרים של הבניינים).
בקשה:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
תשובה:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}