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

בקשה

הפורמט של בקשה ל-Geocoding API הוא:

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

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

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

נדרש HTTPS.

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

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

פרמטרים של קידוד גיאוגרפי (חיפוש קו רוחב/קו אורך)

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

  • address – רחוב או Plus Code שרוצים להמיר לקואורדינטות. יש לציין את הכתובות בהתאם לפורמט שבו נעשה שימוש בשירות הדואר הלאומי של המדינה הרלוונטית. מומלץ להימנע מרכיבים נוספים בכתובת, כמו שמות של עסקים ומספרי יחידות, סוויטות או קומות. רכיבי כתובת פיזית צריכים להיות מופרדים ברווחים (מוצגים כאן כ-url Escape עד %20): 
    address=24%20Sussex%20Drive%20Ottawa%20ON
     צריך לעצב את קודי הפלוס כפי שמוצג כאן (סימני הפלוס צריכים להיות מקודדים כ-%2B וכתובות URL צריכות להיות מקודדות כ-%20):
    • קוד גלובלי הוא קידומת אזור בת 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9 הוא 849VCWC8%2BR9).
    • קוד מורכב הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9 Mountain View, CA, USA הוא CWC8%2BR9%20Mountain%20View%20CA%20USA).

    --OR--
    components — מסנן רכיבים עם רכיבים שמופרדים בקו אנכי (|). מסנן הרכיבים מתקבל גם כפרמטר אופציונלי אם צוין address. כל רכיב במסנן הרכיבים מורכב מזוג של component:value, ומגביל באופן מלא את התוצאות מהקואורדינטות של הקואורדינטות. מידע נוסף על סינון רכיבים מופיע בהמשך.
  • key – מפתח ה-API של האפליקציה שלך. המפתח הזה מזהה את האפליקציה שלכם לצורכי ניהול מכסות. איך מקבלים מפתח

בשאלות הנפוצות מפורטות הנחיות נוספות.

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

  • bounds — תיבת המגבלה של אזור התצוגה שבה מתבצעת הטיה של תוצאות הגיאוקוד כך שיוצגו באופן בולט יותר. הפרמטר הזה ישפיע רק על התוצאות מהמקודד הגיאוגרפי, ולא יגביל אותן לחלוטין. (מידע נוסף זמין בקטע הטיה של חלון התצוגה בהמשך).
  • language – השפה שבה יוחזרו התוצאות.
    • כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא תהיה מקיפה.
    • אם לא תספקו את language, המקודד הגיאוגרפי ינסה להשתמש בשפה המועדפת כפי שצוינה בכותרת Accept-Language, או בשפת האם של הדומיין שממנו הבקשה נשלחת.
    • השירות למיפוי גיאוגרפי עושה כמיטב יכולתו כדי לספק כתובת רחוב שאפשר לקרוא גם למשתמש וגם לאנשים מקומיים. כדי להשיג את המטרה הזו, המערכת מחזירה כתובות רחוב בשפה המקומית, ומעבירה אותן לתווית שקריאתה אפשרית למשתמש, אם יש צורך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרה מהרכיב הראשון.
    • אם שם לא זמין בשפה המועדפת, המערכת למיפוי גיאוגרפי משתמשת בהתאמה הקרובה ביותר.
    • לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שה-API בוחר להחזיר, ועל הסדר שבו הן מוחזרות. המקודד הגיאוגרפי מפרש קיצורים באופן שונה בהתאם לשפה, למשל קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, utca ו-tér הם שמות נרדפים ל'רחוב' ול'כיכר' בהונגרית.
  • region - קוד האזור, שצוין כ-ccTLD ("דומיין ברמה העליונה") בערך בן שני תווים. הפרמטר הזה ישפיע רק על התוצאות של קואורדינטות, ולא יגביל אותן באופן מלא. (למידע נוסף, ראו הטיה לפי אזור בהמשך). הפרמטר יכול להשפיע גם על התוצאות בהתאם לדין החל.
  • components — מסנן רכיבים עם רכיבים שמופרדים בקו אנכי (|). מסנן הרכיבים הוא חובה אם הבקשה לא כוללת address. כל אלמנט במסנן הרכיבים מורכב מצמד component:value, והוא מגביל באופן מלא את התוצאות מהמקודם הגיאוגרפי. בהמשך מפורט מידע נוסף על סינון רכיבים.
  • extra_computations – משתמשים בפרמטר הזה כדי לציין את התכונות הנוספות הבאות בתשובה: כדי להפעיל כמה מהתכונות האלה באותה בקשת 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 לדוגמה.

JSON

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

שימו לב שתגובת ה-JSON מכילה שני רכיבי root:

  • השדה "status" מכיל מטא-נתונים על הבקשה. מידע נוסף מופיע בקטע קודי סטטוס שבהמשך.
  • השדה "results" מכיל מערך של פרטי כתובות שהותאמו למיקום גיאוגרפי ופרטי גיאומטריה.

בדרך כלל, מערכת המיפוי מחזירה רק רשומה אחת במערך "results" לחיפוש כתובות, אבל יכול להיות שהיא תחזיר כמה תוצאות אם שאילתות הכתובות לא ברורות.

XML

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

שימו לב שתגובת ה-XML מורכבת מ-<GeocodeResponse> אחד ומשני רכיבים ברמה העליונה:

  • השדה <status> מכיל מטא-נתונים על הבקשה. מידע נוסף מופיע בקטע קודי סטטוס שבהמשך.
  • אפס רכיבי <result> או יותר, שכל אחד מהם מכיל קבוצה אחת של פרטי כתובת מקודדים ומידע גיאומטרי.

תגובת ה-XML ארוכה בהרבה מתגובת ה-JSON. לכן מומלץ להשתמש ב-json כדגל הפלט המועדף, אלא אם השירות מחייב xml מסיבה כלשהי. בנוסף, עיבוד של עצי XML דורש קצת זהירות, כדי שתוכלו להפנות לרכיבים ולצומתים המתאימים. במאמר ניתוח XML באמצעות XPath מפורטות כמה תבניות תכנון מומלצות לעיבוד פלט.

  • תוצאות ה-XML עטופות ברכיב <GeocodeResponse> ברמה הבסיסית.
  • ב-JSON, רשומות עם כמה רכיבים מסומנות במערכים ברבים (types), ואילו ב-XML הן מסומנות באמצעות כמה רכיבים ביחיד (<type>).
  • אלמנטים ריקים מופיעים באמצעות מערכים ריקים ב-JSON, אבל אין רכיב כזה ב-XML. לדוגמה, תגובה שלא מניבה תוצאות תחזיר מערך results ריק ב-JSON, אבל לא תחזיר רכיבי <result> ב-XML.

קודי סטטוס

השדה "status" באובייקט התשובה של קואורדינטות (geocoding) מכיל את סטטוס הבקשה, ועשוי להכיל מידע על ניפוי באגים כדי לעזור לכם להבין למה הקידוד הגיאוגרפי לא פועל. השדה "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 נוסף בתוך אובייקט התשובה של Geocoding. השדה הזה מכיל מידע מפורט יותר על הסיבות לקוד הסטטוס הנתון.

תוצאות

כשהמקודד לקואורדינטות מחזיר תוצאות, הוא ממקם אותן בתוך מערך results (JSON). גם אם הקואורדינטות לא מחזירות תוצאות (למשל אם הכתובת לא קיימת), הוא עדיין מחזיר מערך results ריק. (תגובות XML מכילות אפס רכיבי <result> או יותר).

תוצאה אופיינית כוללת את השדות הבאים:

  • מערך types[] מציין את הסוג של התוצאה שמוחזרת. המערך הזה מכיל קבוצה של אפס תגים או יותר שמזהים את סוג התכונה שמוחזרת בתוצאה. לדוגמה, כתובת גיאוגרפית של 'תל אביב' מחזירה את הערך 'locality', שמציין ש'תל אביב' היא עיר, וגם את הערך 'political', שמציין שהיא ישות פוליטית. יכול להיות שרכיבים יהיו עם מערך ריק של סוגי כתובות אם אין סוגי כתובות ידועים לרכיב הכתובת הזה. ה-API עשוי להוסיף ערכי סוג חדשים לפי הצורך. מידע נוסף זמין במאמר סוגי כתובות ורכיבי כתובת.
  • formatted_address היא מחרוזת שמכילה את הכתובת של המיקום הזה, שקריאה לבני אדם.

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

    הכתובת הפורמטית מורכבת באופן לוגי מרכיבי כתובת אחד או יותר. לדוגמה, הכתובת 'שדרות רוטשילד 11, תל אביב' מורכבת מהרכיבים הבאים: '111' (המספר ברחוב), 'השדרה השמיני' (המסלול), 'תל אביב' (העיר) ו-'תל אביב' (מדינת ארה"ב).

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

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

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

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

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

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

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

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

  • 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 מציינים את המיקום של תחנת אוטובוס, רכבת או תחבורה ציבורית.

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

בבקשה להמרת כתובות לקואורדינטות (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 הראשית הושקה באופן רשמי. חשוב לזכור שהטיה רק מעדיפה תוצאות של דומיין ספציפי. אם יש תוצאות רלוונטיות יותר מחוץ לדומיין הזה, הן עשויות להיכלל.

לדוגמה, הקוד הגיאוגרפי של 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 מחזירה תוצאה ב-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"
}