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

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

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

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

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

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

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

• language – השפה שבה יוצגו התוצאות.
  • כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא תהיה מקיפה.
  • אם לא מציינים את language, מקודד המיקום מנסה להשתמש בשפה המועדפת כפי שצוינה בכותרת Accept-Language, או בשפה המקומית של הדומיין שממנו נשלחה הבקשה.
  • השירות למיפוי כתובות עושה כמיטב יכולתו כדי לספק כתובת רחוב שאפשר לקרוא גם למשתמש וגם לאנשים מקומיים. כדי להשיג את המטרה הזו, המערכת מחזירה כתובות רחוב בשפה המקומית, עם תעתיק שלהן לכתב שאפשר לקרוא על ידי המשתמש, אם יש צורך, בהתאם לשפה המועדפת. כל הכתובות האחרות יחזרו בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מהרכיב הראשון.
  • אם שם לא זמין בשפה המועדפת, המערכת למיפוי גיאוגרפי משתמשת בהתאמה הקרובה ביותר.
• region – קוד האזור, שמצוין כערך בן שני תווים של דומיין ברמה עליונה עם קוד מדינה (ccTLD). הפרמטר יכול להשפיע גם על התוצאות בהתאם לדין החל.
• result_type – מסנן של סוג כתובת אחד או יותר, שמופרד באמצעות צינור (|). אם הפרמטר מכיל כמה סוגי כתובות, ה-API מחזיר את כל הכתובות שתואמות לאחד מהסוגים. הערה לגבי העיבוד: הפרמטר result_type לא מגביל את החיפוש לסוגים שצוינו של כתובות. במקום זאת, הערך result_type פועל כמסנן לאחר החיפוש: ה-API מאחזר את כל התוצאות של latlng שצוין, ואז משמיד את התוצאות שלא תואמות לסוגים של הכתובות שצוינו. הערכים הבאים נתמכים:
  • 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 מציין נקודת עניין בעלת שם. בדרך כלל, 'נקודות העניין' האלה הן ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו 'בניין האמפייר סטייט' או 'מגדל אייפל'.
• location_type – מסנן של סוג מיקום אחד או יותר, שמופרד באמצעות צינור (|). אם הפרמטר מכיל כמה סוגי מיקום, ה-API מחזיר את כל הכתובות שתואמות לאחד מהסוגים. הערה לגבי העיבוד: הפרמטר location_type לא מגביל את החיפוש לסוגים של המיקומים שצוינו. במקום זאת, השדה location_type פועל כמסנן לאחר החיפוש: ה-API מאחזר את כל התוצאות של latlng שצוין, ולאחר מכן משמיד את התוצאות שלא תואמות לסוגים של המיקומים שצוינו. יש תמיכה בערכים הבאים:
  • הפונקציה "ROOFTOP" מחזירה רק את הכתובות שלגביהן יש ל-Google מידע על המיקום מדויק עד לרמת הרחוב.
  • הפונקציה "RANGE_INTERPOLATED" מחזירה רק את הכתובות שמשקפות הערכה (בדרך כלל על דרך) שעבר אינטרפולציה בין שתי נקודות מדויקות (למשל צמתים). בדרך כלל, טווח משוער מציין שאין קואורדינטות גיאוגרפיות של גגות לכתובת רחוב.
  • "GEOMETRIC_CENTER" מחזירה רק את המרכזים הגיאומטריים של מיקום, כמו קו פוליגון (למשל, רחוב) או פוליגון (אזור).
  • "APPROXIMATE" מחזירה רק את הכתובות שמסווגות ככאלה שהן משוערות.
• extra_computations – אפשר להשתמש בפרמטר הזה כדי לציין את התכונות הנוספות הבאות בתגובה:
  • ADDRESS_DESCRIPTORS – פרטים נוספים זמינים במאמר תיאורי כתובות.
  • BUILDING_AND_ENTRANCES – פרטים נוספים זמינים במאמר כניסות וקווי מתאר של מבנים.
  כדי להפעיל כמה מהתכונות האלה באותה בקשת 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

הערה: חשוב לוודא שאין רווח בין הערכים של קו הרוחב וקו האורך כשהם מועברים בפרמטר latlng.

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

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

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

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

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

הערה: ה-API לא תמיד מחזיר קודי Plus.