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

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

• 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

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

{
   "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) מסוננת לפי סוג

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