בקשה
בקשת Geocoding API מופיעה בצורה הבאה:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
כאשר outputFormat יכול להיות אחד מהערכים הבאים:
json(מומלץ) מציין פלט ב-JavaScript Object Notation (JSON); אוxmlמציין פלט ב-XML
נדרש HTTPS.
חלק מהפרמטרים הם שדות חובה, ויש פרמטרים שהם אופציונליים. בדומה לשימוש סטנדרטי בכתובות URL,
פרמטרים מופרדים באמצעות תו האמפרסנד (&).
שאר הדף מתאר קידוד גיאוגרפי להפוך את הקידוד הגיאוגרפי בנפרד, כי לכל סוג בקשה זמינים פרמטרים שונים.
פרמטרים של קידוד גיאוגרפי (חיפוש קו רוחב/קו אורך)
הפרמטרים הנדרשים בבקשת קידוד גיאוגרפי:
address– הרחוב או ה-Plus Code שרוצים ליצור את הקוד הגיאוגרפי. צריך לציין כתובות בהתאם לפורמט המשמש את שירות הדואר הלאומי של המדינה הרלוונטית. פרטים נוספים רכיבי כתובת כמו שם העסק ומספר היחידה, מספר הדירה או הקומה יש להימנע מכך. רכיבי רחוב צריכים להיות מופרדים ברווחים (מוצג כאן ככתובת URL שמסומנת בתו מילוט (escape) אל%20):address=24%20Sussex%20Drive%20Ottawa%20ON
יש לעצב את ה-Plus Codes כפי שמוצג כאן (הסימן והסימן בתו בריחה (escape) של כתובת ה-URL מופיעים אל%2B, ורווחים באמצעות כתובת ה-URL שמסומנים בתו בריחה (escape) ל-%20:- קוד גלובלי הוא קוד אזור בן 4 תווים ו-6 תווים או יותר
קוד מקומי (849VCWC8+R9 הוא
849VCWC8%2BR9). - קוד מורכב הוא קוד מקומי באורך 6 תווים או יותר עם
מיקום מפורש (CWC8+R9 Mountain View, CA, ארה"ב הוא
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 הם מילים נרדפות ל-Street (רחוב) ו-Square, בהתאמה בהונגרית.
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 מכילה שני רכיבים בסיסיים:
- השדה
"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" בתוך אובייקט התשובה Geocoding מכיל את הסטטוס
של הבקשה, ועשוי לכלול מידע על תוצאות ניפוי הבאגים כדי לעזור לכם להבין את הסיבה לקידוד גיאוגרפי
אינה עובדת. השדה "status" יכול להכיל את הערכים הבאים:
"OK"מציין שלא התרחשו שגיאות; הכתובת שנותחה בהצלחה לפחות קואורדינטות אחד הוחזרו."ZERO_RESULTS"מציין שהקידוד הגיאוגרפי הצליח אבל לא החזיר תוצאות. מצב כזה יכול לקרות אם הועבר באמצעות הקואורדינטותaddressשלא קיימים.OVER_DAILY_LIMITמציין אחת מהאפשרויות הבאות:- מפתח ה-API חסר או לא חוקי.
- לא הופעל חיוב בחשבון.
- חרגת ממכסת השימוש שהוגדרה באופן עצמאי.
- אמצעי התשלום שסופק כבר לא תקף (לדוגמה, פג תוקף כרטיס האשראי).
כדי לקבל מידע נוסף, אפשר לעיין בשאלות הנפוצות בנושא מפות איך לתקן את הבעיה.
"OVER_QUERY_LIMIT"מציין שחרגתם מהמכסה."REQUEST_DENIED"מציין שהבקשה שלך נדחתה."INVALID_REQUEST"מציין בדרך כלל שהשאילתה (address,componentsאוlatlng) חסרים."UNKNOWN_ERROR"מציין שלא ניתן לבקש עובדו בגלל שגיאה בחיבור לשרת. הבקשה עשויה להצליח אם לנסות שוב.
הודעות שגיאה
כשהקואורדינטות מחזירות קוד סטטוס שונה מ-OK, ייתכן שתהיה תוספת של
השדה error_message, בתוך אובייקט התשובה Geocoding. השדה הזה מכיל עוד
מידע מפורט על הסיבות לקוד הסטטוס הנתון.
תוצאות
כשהקואורדינטות מחזירות תוצאות, הוא ממקם אותן בתוך results (JSON)
מערך. גם אם הקואורדינטות לא מחזירות תוצאות (למשל אם הכתובת לא קיימת), הוא עדיין
מחזירה מערך results ריק. (תגובות XML מכילות אפס או יותר
<result> elements.)
תוצאה אופיינית כוללת את השדות הבאים:
- המערך
types[]מציין את הסוג של המוחזר תוצאה אחת. מערך זה מכיל קבוצה של אפס תגים או יותר שמזהים את סוג שחוזרת בתוצאה. לדוגמה, קואורדינטות של "שיקגו" החזרות 'אזור' שמציין ש-"שיקגו" היא עיר, ומחזירה גם את המילה 'political' שמציין שזו ישות פוליטית. יכול להיות שיש סוגים ריקים של רכיבים מערך כאשר אין סוגים ידועים לרכיב הכתובת הזה. ה-API עשוי להוסיף ערכי סוג חדשים לפי הצורך. מידע נוסף זמין במאמר סוגי כתובות ורכיבי כתובת. formatted_addressהיא מחרוזת שמכילה את הטקסט קריא לאנשים של המיקום הזה.בדרך כלל הכתובת הזאת מקבילה לכתובת הדואר. שימו לב: למשל בריטניה, לא מאפשרות הפצה של כתובות למשלוח דואר עקב הגבלות רישוי.
הכתובת המעוצבת מורכבת באופן לוגי מכתובת אחת או יותר רכיבים. לדוגמה, הכתובת "שדרות רוטשילד 11, תל אביב" מורכב מהרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (השדרה 8) (המסלול), "תל אביב" (העיר) ו-"NY" (מדינה בארה"ב).
אין לנתח את הכתובת בפורמט פרוגרמטית. במקום זאת, צריך להשתמש את רכיבי הכתובת הנפרדים, שתגובת ה-API כוללת לשדה הכתובת בפורמט המתאים.
address_components[]הוא מערך שמכיל את הפונקציה הרכיבים הרלוונטיים לכתובת הזו.כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:
types[]הוא מערך שמציין את הסוג של רכיב כתובת. לצפייה ברשימה של סוגים נתמכים.long_nameהוא התיאור או השם של הטקסט המלא של של רכיב הכתובת כפי שהוחזר על ידי ה-Geocoder.short_nameהוא שם טקסט מקוצר של הכתובת רכיב, אם הוא זמין. לדוגמה, רכיב כתובת של המדינה ייתכן שבאלסקה ישlong_nameשל 'אלסקה' וגםshort_nameמתוך "AK" באמצעות קיצור בן 2 אותיות.
חשוב לשים לב לעובדות הבאות לגבי
address_components[]מערך:- מערך רכיבי הכתובת עשוי להכיל יותר רכיבים
formatted_address. - המערך לא כולל בהכרח את כל הישויות הפוליטיות
מכילים כתובת, מלבד הכתובות
formatted_address. כדי לאחזר את כל הישויות הפוליטיות שכוללים כתובת ספציפית, צריך להשתמש בקידוד גיאוגרפי הפוך, קו הרוחב/קו האורך של הכתובת כפרמטר לבקשה. - לא בטוח שפורמט התשובה יישאר זהה
בקשות. באופן ספציפי, המספר של
address_componentsמשתנה בהתאם לכתובת המבוקשת ועשוי להשתנות עם הזמן, אותה כתובת. רכיב יכול לשנות את המיקום במערך. סוג הרכיב יכול להשתנות. רכיב מסוים עשוי להיות חסרה בתשובה מאוחרת יותר.
כדי לטפל במערך הרכיבים, צריך לנתח את התגובה ובוחרים את הערכים המתאימים באמצעות ביטויים. אפשר לעיין במדריך לגבי ניתוח תשובה.
postcode_localities[]הוא מערך שמציין עד 100 רשויות מוניציפאליות בתוך מיקוד. מוצג רק כאשר התוצאה היא דואר שמכיל כמה רשויות מוניציפאליות.geometryמכיל את המידע הבא:locationמכיל את הערך של קו האורך וקו הרוחב המקודד גיאוגרפי. רגיל חיפושי כתובות, בדרך כלל השדה הזה הוא החשוב ביותר.ב-
location_typeנשמרים נתונים נוספים לגבי המיקום שצוין. נכון לעכשיו, המערכת תומכת בערכים הבאים:"ROOFTOP"מציין שהתוצאה שהוחזרה היא קואורדינטות מדויקות של שיש לנו את פרטי המיקום המדויקים עד לרמת הדיוק של הכתובת ברחוב."RANGE_INTERPOLATED"מציין שהתוצאה שהוחזרה משקפת הערכה (בדרך כלל בכביש) שהוחלה בין שתי נקודות מדויקות (כמו צמתים). בדרך כלל מוחזרות תוצאות עם אינטרפולציה כאשר אין ברחוב גישה לקואורדינטות של גגות בניינים address."GEOMETRIC_CENTER"מציין התוצאה שמוחזרת היא המרכז הגאומטרי של תוצאה כמו קו פוליגוני (לדוגמה, רחוב) או פוליגון (אזור)."APPROXIMATE"מציין התוצאה שהוחזרה היא משוערת.
viewportמכיל את אזור התצוגה המומלץ להצגה התוצאה שמוחזרת, מצוינת כשני ערכים של קווי אורך ורוחב שמגדירים אתsouthwestוהקבוצה הפינהnortheastשל התיבה התוחמת של אזור התצוגה. בדרך כלל אזור התצוגה משמש למסגור תוצאה כשמציגים אותה למשתמש.- השדה
bounds(אפשר להחזיר אותו) שומר את התיבה התוחמת שיכול להכיל באופן מלא את התוצאה שמוחזרת. שימו לב שייתכן שהגבולות האלה לא תואמים אזור התצוגה המומלץ. (לדוגמה, סן פרנסיסקו כוללת את איי פארלון, מבחינה טכנית הם חלק מהעיר, אבל ככל הנראה לא להחזיר אותם באזור התצוגה.)
-
plus_code(ראו פתיחת קוד המיקום ו-plus Codes) הם מקודדים שנגזרת מקואורדינטות של קו אורך וקו רוחב, מייצג שטח: 1/8,000 מעלות במעלה 1/8,000 מעלה (בערך 14 מטרים x) 14 מטרים בקו המשווה) או פחות. אפשר להשתמש ב-Plus Codes כתחליף ל- רחובות במקומות שבהם לא קיימות כתובות (כאשר הבניינים לא קיימים ממוספרים או רחובות ללא שמות). ה-API לא תמיד מחזיר קודי OLC.כשהשירות מחזיר OLC, הוא בפורמט של קוד גלובלי וקוד מורכב:
global_codeהוא קוד אזור בן 4 תווים וקוד מקומי באורך 6 תווים או יותר (849VCWC8+R9).compound_codeהוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9, Mountain View, CA, ארה"ב). אין לנתח את התוכן הזה באופן פרוגרמטי.
-
partial_matchמציין שהקואורדינטות לא חזרו התאמה מדויקת לבקשה המקורית, למרות שהיא הצליחה להתאים חלק הכתובת המבוקשת. מומלץ לבדוק את הבקשה המקורית לתיקון שגיאות כתיב ו/או כתובת חלקית.התאמות חלקיות מתרחשות בדרך כלל עבור כתובות של רחובות שאינן קיימות הרשות המוניציפאלית שציינתם בבקשה. התאמות חלקיות עשויות להיות גם שמוחזר כשהבקשה תואמת לשני מיקומים או יותר באותו רשות מוניציפאלית. לדוגמה, "הרצל, ישראל" יחזיר התאמה חלקית לשניהם הנרי סטריט ורחוב הנרייטה. שימו לב שאם בקשה כוללת רכיב הכתובת שגוי, שירות הקידוד הגיאוגרפי עשוי להציע address. גם הצעות שמופעלות באופן הזה יסומנו כהצעות חלקיות. בהתאמה.
place_idהוא ייחודי שאפשר להשתמש בו עם ממשקי API אחרים של Google. לדוגמה, אפשר: להשתמש ב-place_idבקשת Places API כדי לקבל פרטים של עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות ועוד. כאן מופיע מזהה המקום סקירה כללית.
סוגי כתובות וסוגי רכיבי כתובת
המערך types[] בתוצאה מציין את
סוג כתובת. דוגמאות לסוגי כתובת כוללות רחוב,
מדינה או ישות פוליטית. יש גם מערך types[] ב-
address_components[], שמציין את הסוג של כל חלק
address. לדוגמה: מספר בית או מדינה. (בהמשך מופיעה רשימה מלאה של
types.) לכתובות יכולים להיות כמה סוגים. הסוגים יכולים להיחשב כ'תגים'.
לדוגמה, ערים רבות מתויגות באמצעות תגית political
סוג locality.
הקואורדינטות הבאות נתמכות ומוחזרות על ידי הקואורדינטות מערכים של סוג כתובת ורכיב מסוג כתובת:
street_addressמציין כתובת פיזית מדויקת.routeמציין מסלול בעל שם (כגון 'US 101').intersectionמציין צומת ראשי, בדרך כלל שתיים כבישים ראשיים.politicalמציין ישות פוליטית. בדרך כלל, הסוג הזה מציין פוליגון של מנהל אזרחי מסוים.countryמציין את הישות הפוליטית הלאומית, והוא בדרך כלל סוג ההזמנה הגבוה ביותר שהוחזר על ידי ה-Geocoder.administrative_area_level_1מציין מצב אזרחי מסדר ראשון מתחת לרמת המדינה. בתוך ארצות הברית, התנאים האלה רמות מנהליות הן מדינות. לא בכל המדינות רמות מנהליות. ברוב המקרים, admin_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מציין את המיקום של אוטובוס, רכבת או מיקום ציבורי תחנת תחבורה ציבורית.
הטייה של נקודת מבט
בבקשת קידוד גיאוגרפי, ניתן להורות לשירות הקידוד הגיאוגרפי להעדיף
תוצאות בתוך אזור תצוגה נתון (מבוטאת כתיבה תוחמת). עשית את זה
בתוך כתובת ה-URL של הבקשה, על ידי הגדרה של הפרמטר bounds.
הפרמטר bounds מגדיר את הקואורדינטות של קו הרוחב/קו האורך
של הפינות הדרום-מערביות והצפון-מזרחיות של התיבה התוחמת הזו באמצעות צינור
(|) כדי להפריד בין הקואורדינטות.
לדוגמה, קואורדינטות של "וושינגטון" בדרך כלל מחזירה את המדינה בארה"ב וושינגטון:
בקשה:
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 (קוד המדינה ברמה העליונה)
דומיין) שמציין את הטיית האזור. רוב קודי ה-ccTLD זהים ל-
קודי ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, ארצות הברית
הדומיין ברמה העליונה של ccTLD של הממלכה הוא 'uk' (.co.uk) כשקוד ISO 3166-1 שלו הוא "gb"
(טכנית עבור הישות "בריטניה
צפון אירלנד").
ניתן להטות את תוצאות הקידוד הגיאוגרפי לכל דומיין שבו האפליקציה 'מפות Google' הושקה באופן רשמי. לתשומת ליבכם: הטיה בלבד העדפת תוצאות עבור דומיין ספציפי. אם יהיו תוצאות רלוונטיות יותר מחוץ לדומיין הזה, הם עשויים להיכלל.
לדוגמה, קואורדינטות של "Toledo" מחזירה את התוצאה הזו, עבור 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
מחזירה תוצאה בהייסטינגס, אנגליה, במקום בהייסטינגס-און-הדסון, ארה"ב.
בקשה:
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"
}