דף זה תורגם על ידי Cloud Translation API.

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

בקשה

בקשת API לקידוד גיאוגרפי מופיעה בצורה הבאה:

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

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

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

נדרש HTTPS.

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

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

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

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

address — הרחוב או ה-OLC שרוצים לקודד לקואורדינטות. צריך לציין כתובות בהתאם לפורמט שמשמש את שירות הדואר הלאומי של המדינה הרלוונטית. כדאי להימנע מרכיבי כתובת נוספים, כמו שמות עסקים ומספרי יחידות, מספר דירה או קומה. צריך להפריד בין רכיבי הכתובת של הרחוב באמצעות רווחים (מוצג כאן בתור כתובת URL שמסומנת בתו בריחה (escape) עד %20):
```
address=24%20Sussex%20Drive%20Ottawa%20ON
```
הפורמט של הקודים והקודים שמופיעים כאן (עם סימני פלוס הזו מסמנים את ה-URL בתו בריחה (escape) וברווחים הם מסומנים בתו בריחה (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, הקוד לקואורדינטות (geocoding) ינסה להשתמש בשפה המועדפת שצוינה בכותרת Accept-Language, או בשפת האם של הדומיין שממנו הבקשה נשלחת.
- המקודד הגיאוגרפי עושה כמיטב יכולתו כדי לספק כתובת רחוב שתהיה קריאה גם למשתמש וגם למקומיים. כדי להשיג את המטרה הזו, הפונקציה מחזירה כתובות רחובות בשפה המקומית, שמתועתקת לסקריפט שהמשתמש יכול לקרוא במקרה הצורך, תוך תוך שימוש בשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, הנבחרת מהרכיב הראשון.
- אם שם אינו זמין בשפה המועדפת, המקודד הגיאוגרפי ישתמש בהתאמה הקרובה ביותר.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שה-API בוחר להחזיר ועל הסדר שבו הן מוחזרות. המקודד הגיאוגרפי מפרש קיצורים באופן שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אך לא בשפה אחרת. לדוגמה, utca ו-tér הן מילים נרדפות לרחוב ולריבוע בהתאמה בהונגרית.
region - קוד האזור, שמצוין כ-ccTLD ("דומיין ברמה העליונה") בן שני תווים. הפרמטר הזה ישפיע רק על התוצאות מהמקודד לקואורדינטות (geocoding) בלבד. (למידע נוסף, עיינו בקטע תעדוף לפי אזורים בהמשך). הפרמטר יכול גם להשפיע על התוצאות בהתאם לדין החל.
components - מסנן רכיבים עם רכיבים שמופרדים באמצעות קו אנכי (|). מסנן הרכיבים הוא חובה אם הבקשה לא כוללת address. כל רכיב במסנן הרכיבים מורכב מצמד component:value, ומגביל באופן מלא את התוצאות מהמקודד לקואורדינטות. מידע נוסף על סינון רכיבים מופיע בהמשך.

תשובות

תגובות הקידוד הגיאוגרפי מוחזרות בפורמט שצוין על ידי הדגל output בבקשה לכתובת ה-URL, או בפורמט JSON כברירת מחדל.

בדוגמה הזו, ה-Geocoding API מבקש את התשובה json לשאילתה במזהה המקום 'ChIJeRpOeF67j4AR9ydy_PIzPuM'. מזהה המקום הזה הוא של הבניין בכתובת 1600 Amphitheatre Parkway, Mountain View, CA.

הבקשה הזו מדגימה באמצעות הדגל output של JSON:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

בקשה זו מודגמת באמצעות הדגל output של XML:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&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"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

חשוב לשים לב שתגובת JSON מכילה שני רכיבי בסיס:

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

תוצאות

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

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

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

סוגי כתובות וסוגי רכיבים של כתובות

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

בקשה:

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

בקשה לקידוד גיאוגרפי עבור "טולדו" עם 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"
}

סינון רכיבים

בתגובה לקידוד גיאוגרפי, ה-API לקידוד גיאוגרפי יכול להחזיר תוצאות של כתובות שמוגבלות לאזור מסוים. אפשר לציין את ההגבלה באמצעות המסנן components. מסנן מורכב מרשימה של component:value זוגות, שמופרדים באמצעות קו אנכי (|). ערכי המסננים תומכים באותן שיטות לתיקון איות ולהתאמה חלקית כמו בקשות אחרות של קידוד גיאוגרפי. אם המקודד הגיאוגרפי ימצא התאמה חלקית למסנן רכיבים, התשובה תכיל את השדה partial_match.

אפשר לסנן את הנתונים מסוג components:

postal_code תואם עם postal_code ו-postal_code_prefix.
country תואם לשם מדינה או לקוד מדינה בן שתי אותיות ISO 3166-1. ה-API תואם לתקן ISO להגדרת מדינות, והסינון פועל בצורה הטובה ביותר כשמשתמשים בקוד ה-ISO התואם של המדינה.
הערה: אם מתקבלות תוצאות לא צפויות עם קידומת מדינה, עליך לוודא שנעשה שימוש בקוד שכולל את המדינות, הטריטוריות התלויות והאזורים הגיאוגרפיים המיוחדים הרצויים. מידע על קודים זמין במאמר ויקיפדיה: רשימת קודי מדינות בתקן ISO 3166 או בפלטפורמת הגלישה באינטרנט של 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"
}

אפשר להריץ שאילתות חוקיות בלי הפרמטר address באמצעות המסנן 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"
}