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

בקשה

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

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

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

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

נדרש HTTPS.

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

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

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

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

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

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

  עיצוב וקודים כפי שמוצג כאן (השלטים מסומנים בתווי בריחה (escape) לכתובת %2B, ורווחים באמצעות בריחה (escape) לכתובת %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 – הערך היחיד המותר לפרמטר הזה הוא ADDRESS_DESCRIPTORS. אפשר לקרוא פרטים נוספים במאמר תיאורי כתובות.

תשובות

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

• "OK" מציין שלא התרחשו שגיאות; הכתובת עברה ניתוח בהצלחה, והוחזר לפחות קואורדינטות אחד.
• "ZERO_RESULTS" מציין שהקידוד הגיאוגרפי הצליח אבל לא החזיר תוצאות. מצב כזה יכול לקרות אם הועבר באמצעות הקואורדינטות address שלא קיימים.
• OVER_DAILY_LIMIT מציין אחת מהאפשרויות הבאות:
  • מפתח ה-API חסר או לא חוקי.
  • לא הופעל חיוב בחשבון.
  • חרגת ממכסת השימוש שהוגדרה באופן עצמאי.
  • אמצעי התשלום שסופק כבר לא בתוקף (לדוגמה, פג התוקף של כרטיס האשראי).

  כדי להבין איך לפתור את הבעיה, אפשר לעיין בשאלות הנפוצות בנושא מפות Google.

• "OVER_QUERY_LIMIT" מציין שחרגתם מהמכסה.
• "REQUEST_DENIED" מציין שהבקשה שלך נדחתה.
• בדרך כלל, הערך "INVALID_REQUEST" מציין שהשאילתה (address, components או latlng) חסרה.
• "UNKNOWN_ERROR" מציין שלא ניתן היה לעבד את הבקשה בגלל שגיאה בחיבור לשרת. אם תנסו שוב, יכול להיות שהבקשה תאושר.

הודעות שגיאה

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

תוצאות

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

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

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

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

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

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

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

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

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

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

בקשה:

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