מיקום גיאוגרפי – בקשה ותגובה

בקשה

בקשת Geocoding API מופיעה בצורה הבאה:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

כאשר outputFormat יכול להיות אחד מהערכים הבאים:

• json (מומלץ) מציין פלט ב-JavaScript Object Notation ‏(JSON); או
• xml מציין פלט בפורמט XML

נדרש HTTPS.

חלק מהפרמטרים נדרשים וחלקם אופציונליים. כנהוג בכתובות URL, הפרמטרים מופרדים באמצעות התו אמפרסנד (&).

בהמשך הדף מתוארים ביצוע המרה של כתובות לקווי אורך ולרוחב (geocoding) והמרת קואורדינטות לכתובות (reverse geocoding) בנפרד, כי יש פרמטרים שונים לכל סוג של בקשה.

פרמטרים של המרת כתובות לקואורדינטות (חיפוש קו אורך/רוחב)

הפרמטרים הנדרשים בבקשת קידוד גיאוגרפי:

• address – רחוב או Plus Code שרוצים להמיר לקואורדינטות גיאוגרפיות. צריך לציין כתובות בהתאם לפורמט המשמש את שירות הדואר הלאומי של המדינה הרלוונטית. פרטים נוספים רכיבי כתובת כמו שם העסק ומספר יחידה, מספר דירה או קומה יש להימנע מכך. יש להפריד בין רכיבי הרחוב באמצעות רווחים (מוצג כאן כתובת URL עם תווי בריחה %20):

  address=24%20Sussex%20Drive%20Ottawa%20ON

  צריך לעצב את קודי הפלוס כפי שמוצג כאן (סימני הפלוס הם כתובות URL עם תווי בריחה %2B והרווחים הם כתובות URL עם תווי בריחה %20):
  • קוד גלובלי הוא קוד אזור בן 4 תווים ו-6 תווים או יותר קוד מקומי (849VCWC8+R9 הוא 849VCWC8%2BR9).
  • קוד מורכב הוא קוד מקומי בן 6 תווים או יותר עם מיקום מפורש (CWC8+R9 Mountain View, CA, USA הוא CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --או--
  components — מסנן רכיבים עם רכיבים שמפרידים ביניהם צינור (|). אפשר להשתמש במסנן הרכיבים גם כפרמטר אופציונלי אם מציינים address. כל רכיב במסנן הרכיבים מורכב צמד של component:value, שמגביל את התוצאות באופן מלא מהקואורדינטות. בהמשך מפורט מידע נוסף על סינון רכיבים.
• 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 – פרטים נוספים זמינים במאמר כניסות וקווי מתאר של מבנים.
  כדי להפעיל כמה מהתכונות האלה עבור אותה בקשת API, צריך לכלול את הפרמטר 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 לדוגמה.

{
    "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"
}

<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>

קודי סטטוס

השדה "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[] מציין את הסוג של המוחזר תוצאה אחת. מערך זה מכיל קבוצה של אפס תגים או יותר שמזהים את סוג שחוזרת בתוצאה. לדוגמה, קואורדינטות של "שיקגו" החזרות 'אזור' שמציין ש-"שיקגו" היא עיר, ומחזירה גם את המילה 'political' שמציין שזו ישות פוליטית. יכול להיות שיש סוגים ריקים של רכיבים מערך כאשר אין סוגים ידועים לרכיב הכתובת הזה. ה-API עשוי להוסיף ערכים חדשים של סוגים לפי הצורך. מידע נוסף זמין במאמר סוגי כתובות ורכיבי כתובות.
• formatted_address היא מחרוזת שמכילה את הטקסט קריא לאנשים הכתובת של המיקום הזה.

  לרוב, הכתובת הזו זהה לכתובת למשלוח דואר. חשוב לדעת שבמדינות מסוימות, כמו בריטניה, אסור להפיץ כתובות דואר אמיתיות בגלל הגבלות רישוי.

  הכתובת הפורמטית מורכבת באופן לוגי מרכיבי כתובת אחד או יותר. לדוגמה, הכתובת ‎111 8th Avenue, New York, NY‎ מורכבת מהרכיבים הבאים: ‎111‎ (מספר הרחוב), ‎8th Avenue‎ (הדרך), ‎New York‎ (העיר) ו-‎NY‎ (המדינה בארה"ב).

  אין לנתח את הכתובת בפורמט פרוגרמטית. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכלולים בתשובת ה-API בנוסף לשדה הכתובת המעוצב.

• address_components[] הוא מערך שמכיל את הפונקציה הרכיבים הרלוונטיים לכתובת הזו.

  כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:

  • types[] הוא מערך שמציין את הסוג של רכיב כתובת. כאן אפשר לעיין ברשימת הסוגים הנתמכים.
  • long_name הוא התיאור או השם של הטקסט המלא של של רכיב הכתובת כפי שהוחזר על ידי ה-Geocoder.
  • 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 (ראו פתיחת קוד המיקום ו-plus Codes) הם מקודדים שנגזרת מקואורדינטות של קו אורך וקו רוחב, מייצג שטח: 1/8,000 מעלות במעלה 1/8,000 מעלה (בערך 14 מטרים x) 14 מטרים בקו המשווה) או פחות. אפשר להשתמש ב-Plus Codes כתחליף ל- רחובות במקומות שבהם לא קיימות כתובות (כאשר הבניינים לא קיימים ממוספרים או רחובות ללא שמות). ה-API לא תמיד מחזיר קודי Plus.

  כשהשירות מחזיר OLC, הוא בפורמט של קוד גלובלי וקוד מורכב:

  • global_code הוא קוד אזור בן 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9).
  • compound_code הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9,‏ Mountain View,‏ CA,‏ USA). אסור לנתח את התוכן הזה באופן פרוגרמטי.
  במקרים שבהם האפשרות הזו זמינה, ה-API מחזיר גם את הקוד הגלובלי וגם את הקוד המורכב. אבל אם התוצאה נמצאת במיקום מרוחק (לדוגמה: אוקיינוס או מדבר) יכול להיות שיוחזרו קוד גלובלי.

• הערך partial_match מציין שהמקודד הגיאוגרפי לא החזיר התאמה מדויקת לבקשה המקורית, אבל הוא הצליח להתאים חלק מהכתובת המבוקשת. מומלץ לבדוק את הבקשה המקורית לתיקון שגיאות כתיב ו/או כתובת חלקית.

  התאמות חלקיות מתרחשות לרוב בכתובות רחוב שלא קיימות ביישוב שציינתם בבקשה. התאמות חלקיות עשויות להיות גם שמוחזר כשהבקשה תואמת לשני מיקומים או יותר באותו רשות מוניציפאלית. לדוגמה, 'Hillpar St, Bristol, UK' תחזיר התאמה חלקית גם לרחוב Henry וגם לרחוב Henrietta. שימו לב שאם בקשה כוללת רכיב של כתובת עם שגיאת איות, שירות הגיאוקוד עשוי להציע כתובת חלופית. הצעות שתופעלו באופן הזה יסומנו גם כהתאמה חלקית.

• place_id הוא מזהה ייחודי שאפשר להשתמש בו עם ממשקי Google API אחרים. לדוגמה, אפשר להשתמש ב-place_id בבקשה ל-Places API כדי לקבל פרטים על עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות של משתמשים ועוד. כאן מופיע מזהה המקום סקירה כללית.

סוגי כתובות וסוגי רכיבי כתובות

המערך types[] בתוצאה מציין את סוג כתובת. דוגמאות לסוגי כתובות כוללות רחוב, מדינה או ישות פוליטית. יש גם מערך types[] ב- address_components[], שמציין את הסוג של כל חלק address. דוגמאות: מספר בית או מדינה. (בהמשך מופיעה רשימה מלאה של הסוגים). לכתובות יכולים להיות כמה סוגים. הסוגים יכולים להיחשב כ'תגים'. לדוגמה, ערים רבות מתויגות באמצעות תגית political סוג locality.

המערכת תומכת בסוגי המידע הבאים ומחזירה אותם על ידי המקודד הגיאוגרפי גם במערכים של סוגי הכתובות וגם במערכים של סוגי רכיבי הכתובות:

• street_address מציין כתובת רחוב מדויקת.
• route מציין מסלול בעל שם (למשל 'US 101').
• intersection מציין צומת ראשי, בדרך כלל של שני כבישים ראשיים.
• political מציין ישות פוליטית. בדרך כלל, הסוג הזה מציין פוליגון של רשות אזרחית כלשהי.
• הערך country מציין את הישות הפוליטית הלאומית, ובדרך כלל זהו סוג הסדר הגבוה ביותר שמוחזר על ידי המקודד הגיאוגרפי.
• הערך 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 מציין את המיקום של אוטובוס, רכבת או מיקום ציבורי תחנת תחבורה ציבורית.

הטייה של נקודת מבט

בבקשה להמרת כתובות לקואורדינטות (geocoding), אפשר להורות לשירות להעדיף תוצאות בתוך חלון תצוגה נתון (שמוצג כתיבת מלבנית). עשית את זה בתוך כתובת ה-URL של הבקשה, על ידי הגדרה של הפרמטר bounds.

הפרמטר 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 (דומיין ברמה עליונה עם קוד מדינה) שמציינים את ההטיה לאזור. רוב הקודים של TLD ברמת המדינה זהים לקודי 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&region=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"
}