בקשה
בקשה ל-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 שרוצים לבצע להם קידוד גיאוגרפי. צריך לציין את הכתובות בהתאם לפורמט שבו משתמשים בשירות הדואר הלאומי של המדינה הרלוונטית. מומלץ להימנע משימוש ברכיבי כתובת נוספים כמו שמות עסקים ומספרי יחידות, סוויטות או קומות. רכיבי הכתובת צריכים להיות מופרדים ברווחים (מוצגים כאן עם escape לכתובת URL כ-%20):address=24%20Sussex%20Drive%20Ottawa%20ON
%2Bורווחים מוצגים כ-%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 מכילה שני רכיבי בסיס:
-
"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 נוסף באובייקט התגובה של הקידוד הגיאוגרפי. השדה הזה מכיל מידע מפורט יותר על הסיבות לקוד הסטטוס שצוין.
תוצאות
כשגיאוקודר מחזיר תוצאות, הוא ממקם אותן במערך (JSON) results. גם אם הגיאוקודר לא מחזיר תוצאות (למשל אם הכתובת לא קיימת), הוא עדיין מחזיר מערך results ריק. (תשובות XML מורכבות מאפס רכיבים מסוג <result> או יותר).
תוצאה טיפוסית מכילה את השדות הבאים:
- המערך
types[]מציין את הסוג של התוצאה שהוחזרה. המערך הזה מכיל קבוצה של אפס תגים או יותר שמזהים את סוג התכונה שמוחזרת בתוצאה. לדוגמה, אם מזינים את הגיאוקוד של 'שיקגו', המערכת מחזירה את הערך 'locality' (יישוב), שמציין ש'שיקגו' היא עיר, וגם את הערך 'political' (פוליטי), שמציין שזו ישות פוליטית. יכול להיות שהרכיבים יכללו מערך types ריק אם אין סוגים ידועים לרכיב הכתובת הזה. יכול להיות ש-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' באמצעות הקיצור בן 2 האותיות של הדואר.
חשוב לזכור את העובדות הבאות לגבי מערך
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 Code, הוא מפורמט כקוד גלובלי וכקוד מורכב:
-
global_codeהיא קידומת אזור בת 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9). -
compound_codeהוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9, Mountain View, CA, USA). אין לבצע ניתוח תחבירי של התוכן הזה באופן אוטומטי.
-
-
partial_matchמציין שהגיאוקודר לא החזיר התאמה מדויקת לבקשה המקורית, אבל הוא הצליח להתאים חלק מכתובת הבקשה. כדאי לבדוק את הבקשה המקורית כדי לוודא שאין בה שגיאות כתיב או שחסרים בה פרטים בכתובת.התאמות חלקיות מתרחשות לרוב כשמזינים כתובות רחוב שלא קיימות ביישוב שמועבר בבקשה. יכול להיות שיוחזרו גם התאמות חלקיות אם בקשה תתאים לשני מיקומים או יותר באותו אזור. לדוגמה, אם מחפשים את הכתובת "Hillpar St, Bristol, UK", תתקבל התאמה חלקית גם ל-Henry Street וגם ל-Henrietta Street. שימו לב: אם בקשה כוללת רכיב כתובת עם שגיאת כתיב, יכול להיות ששירות הגיאו-קידוד יציע כתובת חלופית. ההצעות שמופעלות בדרך הזו יסומנו גם כהתאמה חלקית.
-
place_idהוא מזהה ייחודי שאפשר להשתמש בו עם ממשקי Google API אחרים. לדוגמה, אפשר להשתמש ב-place_idבבקשה של Places API כדי לקבל פרטים על עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות של משתמשים ועוד. סקירה כללית על מזהה מקום
סוגי כתובות וסוגי רכיבי כתובות
מערך types בתגובה מציין את סוג הכתובת. דוגמאות לסוגי כתובות: כתובת רחוב, מדינה או ישות פוליטית. המערך types בשדה address_component מציין את הסוג של כל חלק בכתובת. לדוגמה, מספר בית או מדינה.
יכולים להיות כמה סוגים של כתובות. אפשר להתייחס לסוגים האלה כאל 'תגים'.
לדוגמה, ערים רבות מתויגות בסוגים political ו-locality.
הסוגים הבאים נתמכים ומוחזרים במערכים של סוג הכתובת וסוג רכיב הכתובת:
| סוג כתובת | תיאור |
|---|---|
street_address |
כתובת רחוב מדויקת. |
route |
מסלול עם שם (לדוגמה, כביש 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 |
נקודת עניין עם שם. בדרך כלל, ה-POI האלה הם ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו Empire State Building או מגדל אייפל. |
רשימה ריקה של סוגים מציינת שאין סוגים ידועים לרכיב הכתובת הספציפי (לדוגמה, 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), אפשר להנחות את שירות ה-Geocoding להעדיף תוצאות בתוך אזור תצוגה נתון (שמוגדר כתיבה תחומת). כדי לעשות זאת, מגדירים את הפרמטר bounds בכתובת ה-URL של הבקשה.
הפרמטר 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 הראשית הושקה באופן רשמי. שימו לב שההטיה רק מעדיפה תוצאות לדומיין ספציפי. אם יש תוצאות רלוונטיות יותר מחוץ לדומיין הזה, יכול להיות שהן ייכללו.
לדוגמה, קידוד גיאוגרפי של 'טולדו' יחזיר את התוצאה הזו, כי דומיין ברירת המחדל של 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"
}
בקשה לגיאו-קידוד של 'טולדו' עם 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, 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"
}