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

בקשה

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

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

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

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

נדרש HTTPS.

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

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

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

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

• key – מפתח ה-API של האפליקציה. המפתח הזה מזהה את האפליקציה שלכם לצורכי ניהול מכסות. איך מקבלים מפתח

• צריך לציין את הערך address או components או את שניהם בבקשה:

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

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

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

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