בקשה
הפורמט של בקשה ל-Geocoding API הוא:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
כאשר outputFormat יכול להיות אחד מהערכים הבאים:
json(מומלץ) מציין פלט ב-JavaScript Object Notation (JSON); אוxmlמציין פלט בפורמט XML
נדרש HTTPS.
חלק מהפרמטרים נדרשים וחלקם אופציונליים. כנהוג בכתובות URL, הפרמטרים מופרדים באמצעות התו אמפרסנד (&).
בהמשך הדף מתוארים ביצוע המרה של כתובות לקווי אורך ורוחבן (geocoding) והמרת קואורדינטות לכתובות (reverse geocoding) בנפרד, כי יש פרמטרים שונים לכל סוג של בקשה.
פרמטרים של המרת כתובות לקואורדינטות (חיפוש קו רוחב/קו אורך)
פרמטרים נדרשים בבקשת גיאוקוד:
key– מפתח ה-API של האפליקציה. המפתח הזה מזהה את האפליקציה שלכם לצורכי ניהול מכסות. איך מקבלים מפתחצריך לציין את הערך
addressאוcomponentsאו את שניהם בבקשה: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).
- קוד גלובלי הוא קידומת חיוג מקומית בת 4 תווים וקוד מקומי באורך 6 תווים או יותר (849VCWC8+R9 הוא
components– מסנן רכיבים עם רכיבים שמפרידים ביניהם צינור (|). אפשר להשתמש במסנן הרכיבים גם כפרמטר אופציונלי אם מצייניםaddress. כל אלמנט במסנן הרכיבים מורכב מצמדcomponent:value, והוא מגביל באופן מלא את התוצאות מהמקודד הגיאוגרפי. בהמשך מפורט מידע נוסף על סינון רכיבים.
הנחיות נוספות זמינות בשאלות הנפוצות.
פרמטרים אופציונליים בבקשת גיאוקוד:
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"מציין שהמיקום הגיאוגרפי נקבע בהצלחה, אבל לא הוחזרו תוצאות. מצב כזה יכול לקרות אם הועברו למקודם הגיאוגרפית נתוני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_component מציין את הסוג של כל חלק בכתובת. דוגמאות: מספר בית או מדינה.
לכתובות יכולים להיות כמה סוגים. אפשר להתייחס לסוגי הנתונים האלה כ 'תגים'.
לדוגמה, ערים רבות מתויגות בסוגי התגים political ו-locality.
יש תמיכה בסוגי הנתונים הבאים, והם מוחזרים גם במערך של סוג הכתובת וגם במערך של סוג רכיב הכתובת:
| סוג כתובת | תיאור |
|---|---|
street_address |
כתובת רחוב מדויקת. |
route |
מסלול בעל שם (למשל, 'כביש 6'). |
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"
}
בקשה ליצירת כתובת מ-Geocoding עבור '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"
}