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

בקשה

בקשת Geocoding API נראית כך:

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

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

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

חובה להשתמש ב-HTTPS.

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

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

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

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

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

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

  • ‫address – הכתובת או ה-Plus Code שרוצים להמיר לקואורדינטות. הערה: המרת כתובות לקואורדינטות לא פותרת קואורדינטות של קווי רוחב ואורך, או מחרוזות לא מובנות אחרות שלא מייצגות כתובת או Plus Code. בקשות שכוללות מחרוזות כאלה לא נתמכות, ועלולות להוביל לתגובות שגיאה או להתנהגות לא מוגדרת. דוגמאות לשאילתות שלא נתמכות:

    סוג השאילתה	דוגמה
    קואורדינטות של קווי רוחב ואורך. במקום זאת, צריך להשתמש בהמרת קואורדינטות לכתובות (reverse geocoding).	"37.422131,-122.084801"
    יותר מדי מושגים או אילוצים, כמו שמות של כמה מקומות, כבישים או ערים בשאילתה אחת	"Market Street San Francisco San Jose Airport"
    רכיבים של כתובת דואר שלא מיוצגים במפות Google	"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco"
    שמות של עסקים, רשתות או קטגוריות בשילוב עם מיקומים שבהם הישויות האלה לא זמינות	"Tesco near Dallas, Texas"
    שאילתות מעורפלות עם כמה פרשנויות	"החזרת מטען"
    שמות היסטוריים שכבר לא בשימוש	"Middlesex United Kingdom"
    רכיבים או כוונה שאינם גיאו-מרחביים	"כמה סירות יש בנמל ונטורה?"
    שמות לא רשמיים או שמות מותאמים אישית	"The Jenga" "The Helter Skelter"

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

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

    צריך להזין את קודי Plus Code בפורמט שמוצג כאן (סימני פלוס מומרים ל-%2B ורווחים מומרים ל-%20):
    • global code הוא קוד אזור בן 4 תווים וקוד מקומי באורך של 6 תווים או יותר (849VCWC8+R9 הוא 849VCWC8%2BR9).
    • קוד מורכב הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9 Mountain View, CA, USA הוא CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • ‫components – מסנן רכיבים עם אלמנטים שמופרדים באמצעות קו אנכי (|). מסנן הרכיבים מתקבל גם כפרמטר אופציונלי אם צוין address. כל רכיב במסנן הרכיבים מורכב מזוג component:value, ומגביל באופן מלא את התוצאות מהכלי להמרת כתובות לקואורדינטות (geocoder). מידע נוסף על סינון רכיבים מופיע בהמשך.

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

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

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

הבקשה הזו מדגימה שימוש בדגל ה-JSON‏ output:

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" מציין שהמרת הכתובת לקואורדינטות הצליחה, אבל לא הוחזרו תוצאות. זה יכול לקרות אם לכלי להמרת כתובות לקואורדינטות (geocoder) הועבר 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[] מציין את ה-type של התוצאה שהתקבלה. המערך הזה מכיל קבוצה של אפס תגים או יותר שמזהים את סוג התכונה שמוחזרת בתוצאה. לדוגמה, המרת הכתובת "Chicago" לקואורדינטות מחזירה את הערך locality, שמציין ש-Chicago היא עיר, וגם את הערך political, שמציין שהיא ישות פוליטית. מידע נוסף זמין במאמר סוגי כתובות וסוגי רכיבים של כתובות.
• ‫formatted_address הוא מחרוזת שמכילה את הכתובת של המיקום הזה, שקריאה לאנשים.

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

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

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

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

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

  • ‫types[] הוא מערך שמציין את הסוג של רכיב הכתובת. יכול להיות שרכיב הכתובת יכלול מערך סוגים ריק אם אין סוגים ידועים לרכיב הכתובת הזה. יכול להיות שה-API יוסיף ערכי סוג חדשים לפי הצורך. מידע נוסף זמין במאמר סוגי כתובות וסוגי רכיבים של כתובות.
  • ‫long_name הוא תיאור הטקסט המלא או השם של רכיב הכתובת, כפי שהוחזר על ידי הכלי להמרת כתובות לקואורדינטות (geocoder).
  • ‫short_name הוא שם טקסטואלי מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של מדינת אלסקה יכול לכלול long_name של "אלסקה" ו-short_name של "AK" באמצעות קיצור הדואר בן 2 האותיות.

  שימו לב לעובדות הבאות לגבי המערך address_components[]:

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

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

  • ‫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_component מציין את הסוג של כל חלק בכתובת. לדוגמה, מספר בית או מדינה.

לכתובות יכולים להיות כמה סוגים. אפשר להתייחס לסוגים כאל "תגים". לדוגמה, ערים רבות מתויגות בסוגים political ו-locality.

אלה הסוגים הנתמכים שמוחזרים גם במערך של סוג הכתובת וגם במערך של סוג רכיב הכתובת:

רשימה ריקה של סוגים מציינת שאין סוגים ידועים לרכיב הכתובת הספציפי (לדוגמה, Lieu-dit בצרפת).

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

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

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

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

לדוגמה, המרת הכתובת "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 שמגדיר תיבה תוחמת (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"
}

בקשה להמרת כתובת לקואורדינטות של "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, ‏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"
}

בקשה להמרת כתובת לקואורדינטות של היישוב "Santa Cruz" עם components=country:ES מחזירה את Santa Cruz de Tenerife באיים הקנריים, ספרד.

בקשה:

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