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

בקשה

הבקשה ל-Geocoding API בנויה כך:

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

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

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

נדרש HTTPS.

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

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

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

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

• street_address מציין כתובת רחוב מדויקת.
• route מציין מסלול בעל שם (למשל, 'US 101').
• intersection מציין צומת ראשי, בדרך כלל של שני כבישים ראשיים.
• political מציין ישות פוליטית. בדרך כלל, הסוג הזה מציין פוליגון של רשות אזרחית כלשהי.
• הערך country מציין את הישות הפוליטית הלאומית, והוא בדרך כלל סוג הסדר הגבוה ביותר שמוחזר על ידי המקודד הגיאוגרפי.
• הערך administrative_area_level_1 מציין ישות אזרחית ברמה ראשונה מתחת לרמת המדינה. בארצות הברית, הרמות האלה הן המדינות. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית. ברוב המקרים, השמות המקוצרים של administrative_area_level_1 יהיו דומים מאוד לחלוקות משנה של ISO 3166-2 ולרשימות אחרות שפורסמו באופן נרחב. עם זאת, אין ערובה לכך כי תוצאות הגיאוקוד מבוססות על מגוון אותות ונתוני מיקום.
• administrative_area_level_2 מציין ישות אזרחית ברמה שנייה מתחת לרמת המדינה. בארצות הברית, הרמות האלה הן מחוזות. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.
• administrative_area_level_3 מציין ישות אזרחית של סדר שלישי מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.
• administrative_area_level_4 מציין ישות אזרחית ברמה הרביעית מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.
• administrative_area_level_5 מציין ישות אזרחית ברמה החמישית מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את רמות הניהול האלה.
• administrative_area_level_6 מציין ישות אזרחית מדרג שישי מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.
• administrative_area_level_7 מציין ישות אזרחית מסדר שביעי מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.
• colloquial_area מציין שם חלופי נפוץ של הישות.
• locality מציין ישות פוליטית של עיר או עיירה מאוחדת.
• sublocality מציין ישות אזרחית מדרגה ראשונה מתחת לאזור גיאוגרפי. יכול להיות שחלק מהמיקומים יקבלו אחד מהסוגים הנוספים: sublocality_level_1 עד sublocality_level_5. כל רמת יישוב משנה היא ישות אזרחית. מספרים גדולים יותר מציינים אזור גיאוגרפי קטן יותר.
• neighborhood מציין שכונה בעלת שם.
• premise מציין מיקום בעל שם, בדרך כלל בניין או אוסף של בניינים עם שם משותף.
• subpremise מציין ישות שניתן לשלוח אליה הודעות מתחת לרמת המקום, כמו דירה, יחידה או סוויטה.
• plus_code מציין הפניה מקודדת למיקום, שמבוססת על קו הרוחב וקווי האורך. אפשר להשתמש ב-Plus Codes כתחליף לכתובות רחוב במקומות שבהם הן לא קיימות (במקומות שבהם אין מספרי בניינים או שמות רחובות). פרטים נוספים זמינים בכתובת https://plus.codes.
• postal_code מציין מיקוד שמשמש לכתובת של דואר בתוך המדינה.
• natural_feature מציין תכונה טבעית בולטת.
• airport מציין נמל תעופה.
• park מציין פארק בעל שם.
• point_of_interest מציין נקודת עניין בעלת שם. בדרך כלל, 'נקודות העניין' האלה הן ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו 'בניין האמפייר סטייט' או 'מגדל אייפל'.

רשימה ריקה של סוגים מציינת שאין סוגים ידועים לרכיב הכתובת הספציפי, למשל Lieu-dit בצרפת.

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

• floor מציין את הקומה בכתובת של מבנה.
• הערך establishment בדרך כלל מציין מקום שעדיין לא שויך לקטגוריה.
• landmark מציין מקום קרוב שמשמש כנקודת עזר לניווט.
• point_of_interest מציין נקודת עניין בעלת שם.
• parking מציין חניון או מגרש חניה.
• post_box מציין תיבת דואר ספציפית.
• postal_town מציין קיבוץ של אזורים גיאוגרפיים, כמו locality ו-sublocality, המשמש לכתובות למשלוח דואר במדינות מסוימות.
• room מציין את החדר בכתובת של מבנה.
• street_number מציין את מספר הבית המדויק.
• bus_station, ‏ train_station ו-transit_station מציינים את המיקום של תחנת אוטובוס, רכבת או תחבורה ציבורית.

הטיה של אזור התצוגה

בבקשת גיאוקוד, אפשר להורות לשירות הגיאוקוד להעדיף תוצאות בתוך חלון תצוגה נתון (שמוצג כתיבת מלבנית). כדי לעשות זאת, מגדירים את הפרמטר 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 (דומיין ברמה עליונה עם קוד מדינה) שמציינים את ההטיה לאזור. רוב הקודים של TLD ברמת המדינה זהים לקודי ISO 3166-1, מלבד כמה יוצאים מן הכלל. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא 'uk' (.co.uk), ואילו הקוד שלה לפי תקן ISO 3166-1 הוא 'gb' (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד').

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

לדוגמה, כתובת גיאוגרפית של 'טולדו' מחזירה את התוצאה הזו, כי דומיין ברירת המחדל של Geocoding API מוגדר לארצות הברית. בקשה:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

תשובה:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

בקשה ליצירת כתובת ממיקוד גיאוגרפי של 'Toledo' עם region=es (ספרד) תחזיר את העיר בספרד.

בקשה:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&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 מחזירה תוצאה ב-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"
}