בקשה ותגובה לקידוד גיאוגרפי הפוך (חיפוש כתובת)

מפתחים באזור הכלכלי האירופי (EEA)

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

בקשות להמרת קואורדינטות לכתובות (reverse geocoding)

פרמטרים נדרשים

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

פרמטרים אופציונליים

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

  • ‫language – השפה שבה יוצגו התוצאות.
    • כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
    • אם לא תספקו את language, הגיאוקודר ינסה להשתמש בשפה המועדפת שצוינה בכותרת Accept-Language, או בשפה המקומית של הדומיין שממנו נשלחה הבקשה.
    • הגיאוקודר עושה כמיטב יכולתו כדי לספק כתובת רחוב שגם המשתמש וגם תושבי המקום יוכלו לקרוא. כדי להשיג את המטרה הזו, הוא מחזיר כתובות בשפה המקומית, בתעתיק לכתב שניתן לקריאה על ידי המשתמש אם יש צורך בכך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מתוך הרכיב הראשון.
    • אם שם לא זמין בשפה המועדפת, הגיאוקודר משתמש בהתאמה הקרובה ביותר.
  • ‫region – קוד האזור, שמצוין כערך של שני תווים של ccTLD (דומיין ברמה העליונה). הפרמטר יכול גם להשפיע על התוצאות בהתאם לדין החל.
  • ‫result_type – מסנן של סוג כתובת אחד או יותר, שמופרדים באמצעות קו אנכי (|). אם הפרמטר מכיל כמה סוגי כתובות, ה-API מחזיר את כל הכתובות שתואמות לאחד מהסוגים. הערה לגבי עיבוד: הפרמטר result_type לא מגביל את החיפוש לסוגי הכתובות שצוינו. במקום זאת, הפונקציה result_type פועלת כמסנן אחרי החיפוש: ה-API מאחזר את כל התוצאות של latlng שצוין, ואז מסיר את התוצאות שלא תואמות לסוגי הכתובות שצוינו. הערכים הבאים נתמכים:

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

    מערך types בגוף GeocodeResult בתגובה מציין את סוג הכתובת. דוגמאות לסוגי כתובות: כתובת רחוב, מדינה או ישות פוליטית. המערך types בשדה AddressComponents של גוף GeocodeResult מציין את הסוג של כל חלק בכתובת. לדוגמה, מספר בית או מדינה.

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

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

    סוג כתובת תיאור
    street_address כתובת רחוב מדויקת.
    route מסלול עם שם (לדוגמה, כביש 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 נקודת עניין עם שם. בדרך כלל, ה-POI האלה הם ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו Empire State Building או מגדל אייפל.

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

  • ‫location_type – מסנן של סוג מיקום אחד או יותר, שמופרדים באמצעות קו אנכי (|). אם הפרמטר מכיל כמה סוגי מיקום, ה-API מחזיר את כל הכתובות שתואמות לאחד מהסוגים. הערה לגבי עיבוד: הפרמטר location_type לא מגביל את החיפוש לסוגי המיקומים שצוינו. במקום זאת, הפונקציה location_type פועלת כמסנן אחרי החיפוש: ה-API מאחזר את כל התוצאות של latlng שצוין, ואז מסיר את התוצאות שלא תואמות לסוגי המיקומים שצוינו. יש תמיכה בערכים הבאים:
    • ‫"ROOFTOP" מחזירה רק את הכתובות שלגביהן ל-Google יש פרטי מיקום ברמת דיוק של כתובת.
    • ‫"RANGE_INTERPOLATED" מחזירה רק את הכתובות שמשקפות קירוב (בדרך כלל בכביש) שחושב על סמך אינטרפולציה בין שתי נקודות מדויקות (למשל, צמתים). טווח משוער בדרך כלל מציין שאין קודי מיקום של גגות לכתובת מסוימת.
    • ‫"GEOMETRIC_CENTER" מחזירה רק מרכזים גיאומטריים של מיקום כמו קו פוליגוני (לדוגמה, רחוב) או פוליגון (אזור).
    • ‫"APPROXIMATE" מחזירה רק את הכתובות שמסווגות כמשוערות.
  • extra_computations — משתמשים בפרמטר הזה כדי לציין את התכונות הנוספות הבאות בתגובה: כדי להפעיל כמה מהתכונות האלה באותה בקשה ל-API, צריך לכלול את הפרמטר extra_computations בבקשה לכל תכונה, לדוגמה: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

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

דוגמה להמרת קואורדינטות לכתובות (reverse geocoding)

השאילתה הבאה מכילה את ערך קו הרוחב/קו האורך של מיקום בברוקלין:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

השאילתה שלמעלה מחזירה את התוצאה הבאה:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

שימו לב שהגיאוקודר ההפוך החזיר יותר מתוצאה אחת. "formatted_address" התוצאות לא כוללות רק כתובות למשלוח דואר, אלא כל דרך לתת שם גיאוגרפי למיקום. לדוגמה, כשמבצעים גיאו-קידוד של נקודה בעיר שיקגו, יכול להיות שהנקודה המקודדת תצוין ככתובת רחוב, כעיר (שיקגו), כמדינה (אילינוי) או כמדינה (ארצות הברית). כולן הן 'כתובות' עבור הגיאוקודר. הגיאוקודר ההפוך מחזיר כל אחד מהסוגים האלה כתוצאות תקינות.

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

בהמשך מופיעה הרשימה המלאה של ערכי formatted_address שמוחזרים על ידי השאילתה הקודמת.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

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

המרת קואורדינטות לכתובות (reverse geocoding) מסוננת לפי סוג

בדוגמה הבאה, הכתובות שמוחזרות מסוננות כך שיכללו רק כתובות עם סוג מיקום ROOFTOP וסוג כתובת street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

הערה: המסננים האלה תקפים רק עבור גיאו-קידוד הפוך.

תשובות של המרת קואורדינטות לכתובות (reverse geocoding)

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

קודי סטטוס של המרת קואורדינטות לכתובות (reverse geocoding)

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

  • ‫"OK" מציין שלא אירעו שגיאות והוחזרה לפחות כתובת אחת.
  • ‫"ZERO_RESULTS" מציין שהגיאוקודינג ההפוך הצליח אבל לא הוחזרו תוצאות. זה יכול לקרות אם הועבר לגיאוקודר latlng במיקום מרוחק.
  • ‫"OVER_QUERY_LIMIT" מציין שחרגתם מהמכסה.
  • ‫"REQUEST_DENIED" מציין שהבקשה נדחתה. יכול להיות שהסיבה לכך היא שהבקשה כוללת פרמטר result_type או location_type אבל לא כוללת מפתח API.
  • הערך "INVALID_REQUEST" מציין בדרך כלל אחת מהאפשרויות הבאות:
    • השאילתה (address, components או latlng) חסרה.
    • צוין ערך לא תקין של result_type או location_type.
  • ‫"UNKNOWN_ERROR" מציין שלא ניתן היה לעבד את הבקשה בגלל שגיאה בחיבור לשרת. יכול להיות שהבקשה תצליח אם תנסו שוב.

המרת קואורדינטות לכתובות (reverse geocoding) של קודי OLC

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