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

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

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

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

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

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

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

• language – השפה שבה יוצגו התוצאות.
  • כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, לכן היא חלקית.
  • אם לא מציינים את language, המקודד הגיאוגרפי מנסה להשתמש בשפה המועדפת כפי שצוינה בכותרת Accept-Language, או בשפה המקומית של הדומיין שממנו נשלחת הבקשה.
  • הקואורדינטות עושה כמיטב יכולתו כדי לספק כתובת קריא גם למשתמש וגם לתושבים המקומיים. כדי להשיג את המטרה הזו, המערכת מחזירה כתובות רחוב בשפה המקומית, שמומרות לתסריט שאפשר לקרוא אותו על ידי המשתמש, אם יש צורך, בהתאם לשפה המועדפת. כל הכתובות האחרות יחזרו בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחר מהרכיב הראשון.
  • אם השם לא זמין בשפה המועדפת, הקואורדינטות משתמשות בו את ההתאמה הכי קרובה.
• region – קוד האזור, מצוין כ-ccTLD ("דומיין ברמה עליונה") ערך של שני תווים. הפרמטר יכול להשפיע גם על על סמך הדין החל.
• result_type - מסנן מסוג אחד או יותר של כתובות, שמופרדות בקו אנכי (|). אם הפרמטר מכיל addresss, ה-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.

דוגמה לקידוד גיאוגרפי הפוך

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

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