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

בקשה

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

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

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

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

נדרש HTTPS.

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

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

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

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

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

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

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

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

  • bounds – התיבה התוחמת של אזור התצוגה שבה תהיה הטיה של התוצאות הגיאוגרפיות באופן בולט יותר. הפרמטר הזה ישפיע רק על התוצאות מהמקודד הגיאוגרפי, ולא יגביל אותן לחלוטין. (מידע נוסף זמין בקטע הטיה של חלון התצוגה בהמשך).
  • language – השפה שבה צריך תוצאות מוחזרות.
    • לרשימת האפליקציות הנתמכות שפות מסוימות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, היא חלקית.
    • אם לא תספקו את language, המקודד הגיאוגרפי ינסה להשתמש בשפה המועדפת כפי שמצוין ב- הכותרת Accept-Language, או שפת האם של הדומיין שממנו הבקשה נשלחת.
    • הקואורדינטות עושה כמיטב יכולתו כדי לספק כתובת קריא גם למשתמש וגם לתושבים המקומיים. כדי להשיג את המטרה הזו, מחזירה כתובות של רחובות בשפה המקומית, בתעתיק סקריפט קריא על ידי המשתמש במקרה הצורך, תוך שמירה על בשפת היעד. כל שאר הכתובות מוחזרות בשפת היעד. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחר מהרכיב הראשון.
    • אם השם לא זמין בשפה המועדפת, הקואורדינטות משתמשות בו את ההתאמה הכי קרובה.
    • לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שה-API בוחר להחזיר ועל הסדר שבו הן מוחזרות. המערכת למיפוי גיאוגרפי מפענחת קיצורים באופן שונה בהתאם לשפה, למשל קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, utca ו-tér הם מילים נרדפות ל-Street (רחוב) ו-Square, בהתאמה בהונגרית.
  • region – קוד האזור, מצוין כ-ccTLD ("דומיין ברמה עליונה") ערך של שני תווים. הפרמטר הזה יגרום רק השפעה, מבלי להגביל באופן מלא, את התוצאות מהקואורדינטות של הקואורדינטות. (לקבלת מידע נוסף מידע נוסף מופיע בקטע הטיה לפי אזור שבהמשך). יכול להשפיע גם על התוצאות בהתאם לחוק הרלוונטי.
  • components – מסנן רכיבים עם רכיבים שמפרידים ביניהם צינור (|). מסנן הרכיבים נדרש אם הבקשה לא כוללת address. כל אלמנט במסנן הרכיבים מורכב מצמד component:value, והוא מגביל באופן מלא את התוצאות מהמקודם הגיאוגרפי. מידע נוסף על סינון רכיבים שבהמשך.
  • extra_computations – משתמשים בפרמטר הזה כדי לציין את את התכונות הנוספות הבאות בתשובה: כדי להפעיל כמה מהתכונות האלה עבור אותה בקשת API, צריך לכלול את extra_computations של הפרמטר בבקשה לכל תכונה, לדוגמה:
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

תשובות

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

בדוגמה זו, Geocoding API מבקש json תגובה לשאילתה בכתובת "1600 Amphitheatre Parkway, Mountain View, CA".

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

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

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

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

בכרטיסיות שלמטה ניתן לראות תגובות JSON ו-XML לדוגמה.

JSON

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

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

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

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

XML

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

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

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

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

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

קודי סטטוס

השדה "status" בתוך אובייקט התשובה Geocoding מכיל את הסטטוס של הבקשה, ועשוי לכלול מידע על תוצאות ניפוי הבאגים כדי לעזור לכם להבין את הסיבה לקידוד גיאוגרפי אינה עובדת. השדה "status" יכול להכיל את הערכים הבאים:

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

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

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

הודעות שגיאה

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

תוצאות

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

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

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

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

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

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

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

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

    • types[] הוא מערך שמציין את הסוג של רכיב כתובת. לצפייה ברשימה של סוגים נתמכים.
    • long_name הוא התיאור או השם של הטקסט המלא של של רכיב הכתובת כפי שהוחזר על ידי ה-Geocoder.
    • 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" מציין שהתוצאה שמוחזרת משקפת הערכה (בדרך כלל על דרך) שעבר תהליך אינטרפולציה בין שתי נקודות מדויקות (כמו צמתים). בדרך כלל מוחזרות תוצאות עם אינטרפולציה כאשר אין ברחוב גישה לקואורדינטות של גגות בניינים address.
      • "GEOMETRIC_CENTER" מציין התוצאה שמוחזרת היא המרכז הגאומטרי של תוצאה כמו קו פוליגוני (לדוגמה, רחוב) או פוליגון (אזור).
      • "APPROXIMATE" מציין שהתוצאה שהתקבלה היא משוערת.
    • השדה viewport מכיל את אזור התצוגה המומלץ להצגת התוצאה שהתקבלה, שצוין בשני ערכים של קו הרוחב ואורך הגלובוס שמגדירים את הפינות southwest ו-northeast של תיבת הגבול של אזור התצוגה. בדרך כלל, חלון התצוגה משמש להצגת תוצאה למשתמש.
    • השדה bounds (אפשר להחזיר אותו) שומר את התיבה התוחמת שיכול להכיל באופן מלא את התוצאה שמוחזרת. שימו לב שייתכן שהגבולות האלה לא תואמים אזור התצוגה המומלץ. (לדוגמה, סן פרנסיסקו כוללת את איי פרלון, ששייכים טכנית לעיר, אבל סביר להניח שלא כדאי להציג אותם בחלון התצוגה).
  • plus_code (ראו Open Location Code וPlus Codes) הוא הפניה מקודדת למיקום, שמבוססת על קואורדינטות של קווי אורך ורוחב, שמייצגת אזור: 1/8000 מעלה על 1/8000 מעלה (כ-14 מ' על 14 מ' בקווי הרוחב) או קטן יותר. אפשר להשתמש ב-Plus Codes כתחליף ל- רחובות במקומות שבהם לא קיימות כתובות (כאשר הבניינים לא קיימים ממוספרים או רחובות ללא שמות). ה-API לא תמיד מחזיר קודי OLC.

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

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

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

  • place_id הוא ייחודי שאפשר להשתמש בו עם ממשקי API אחרים של Google. לדוגמה, אפשר: להשתמש ב-place_id בקשת Places API כדי לקבל פרטים של עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות ועוד. כאן מופיע מזהה המקום סקירה כללית.

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

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

בקשה:

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