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

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

היפוך של בקשות לקידוד גיאוגרפי

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

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

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

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

• language – השפה שבה יוחזרו התוצאות.
  • לרשימת השפות הנתמכות Google מעדכנת את השפות הנתמכות לעיתים קרובות, ולכן ייתכן שזו רשימה חלקית בלבד.
  • אם לא תספקו את language, המקודד הגיאוגרפי ינסה להשתמש בשפה המועדפת כפי שצוינה בכותרת Accept-Language, או בשפת האם של הדומיין שממנו הבקשה נשלחת.
  • הקואורדינטות עושה כמיטב יכולתו כדי לספק כתובת שניתנת לקריאה גם למשתמש וגם לתושבים המקומיים. כדי להשיג את המטרה הזו, המערכת מחזירה כתובות של רחובות בשפה המקומית, מתועתק לסקריפט שהמשתמש יכול לקרוא במקרה הצורך, תוך שמירה על השפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרה מהרכיב הראשון.
  • אם השם לא זמין בשפה המועדפת, המקודד הגיאוגרפי משתמש בהתאמה הקרובה ביותר.
• region - קוד האזור, שצוין כ-ccTLD ("דומיין ברמה העליונה") כערך בן שני תווים. הפרמטר יכול גם להשפיע על התוצאות בהתאם לדין החל.
• result_type – מסנן של סוג כתובת אחד או יותר, מופרדים באמצעות קו אנכי (|). אם הפרמטר מכיל כמה סוגי כתובות, ה-API יחזיר את כל הכתובות שתואמות לכל אחד מהסוגים. הערה לגבי עיבוד: הפרמטר result_type לא restrict את החיפוש לסוגי הכתובות שצוינו. במקום זאת, result_type משמש כמסנן לאחר החיפוש: ה-API מאחזר את כל התוצאות של latlng שצוין, ואז מוחקת את התוצאות שלא תואמות לסוגי הכתובות שצוינו. הערכים הבאים נתמכים:
  • street_address מציין כתובת פיזית מדויקת.
  • route מציין מסלול בעל שם (כגון 'US 101').
  • intersection מציין צומת ראשי, בדרך כלל כולל שתי כבישים ראשיים.
  • political מציין ישות פוליטית. בדרך כלל, הסוג הזה מציין פוליגון של ניהול אזרחי מסוים.
  • country מציין את הישות הפוליטית הלאומית, ובדרך כלל זהו סוג הסדר הגבוה ביותר שהוחזר על ידי הקואורדינטות.
  • administrative_area_level_1 מציין ישות אזרחית מסדר ראשון שנמצאת מתחת לרמת המדינה. בארה"ב, הרמות המנהליות האלה הן מדינות. לא בכל המדינות יש רמות ניהול כאלה. ברוב המקרים, השמות המקוצרים של admin_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 כתחליף לכתובות של רחובות במקומות שבהם הן לא קיימות (כאשר בניינים לא ממוספרים או אין שמות של רחובות). פרטים נוספים זמינים בכתובת https://plus.codes.
  • postal_code מציין מיקוד שמשמש לכתובת דואר בתוך המדינה.
  • natural_feature מציין ישות טבעית בולטת.
  • airport מציין שדה תעופה.
  • park מציין פארק בעל שם.
  • point_of_interest מציין נקודת עניין עם שם. בדרך כלל, נקודות העניין האלה הן ישויות מקומיות בולטות שלא מתאימים בקלות לקטגוריה אחרת, כמו 'בניין האמפייר סטייט' או 'מגדל אייפל'.
• location_type — מסנן של סוג מיקום אחד או יותר, מופרדים באמצעות קו אנכי (|). אם הפרמטר מכיל כמה סוגי מיקומים, ה-API יחזיר את כל הכתובות שתואמות לכל אחד מהסוגים. הערה לגבי עיבוד: הפרמטר location_type לא restrict את החיפוש לסוגי המיקום שצוינו. במקום זאת, location_type משמש כמסנן לאחר החיפוש: ה-API מאחזר את כל התוצאות של latlng שצוין, ואז מוחק את התוצאות האלה שלא תואמות לסוגי המיקומים שצוינו. הערכים הבאים נתמכים:
  • "ROOFTOP" מחזירה רק את הכתובות שלגביהן יש ל-Google את פרטי המיקום המדויקים עד לרמת הדיוק של הכתובת הפיזית.
  • "RANGE_INTERPOLATED" מחזיר רק את הכתובות שמשקפות הערכה (בדרך כלל בכביש) שמשולבות בין שתי נקודות מדויקות (כמו צמתים). בדרך כלל, טווח אינטרפולטיבי מציין שהקואורדינטות על הגגות לא זמינות בכתובת מסוימת.
  • הפונקציה "GEOMETRIC_CENTER" מחזירה רק מרכזים גיאומטריים של מיקום, כמו קו פוליגוני (למשל רחוב) או פוליגון (אזור).
  • הפונקציה "APPROXIMATE" מחזירה רק את הכתובות שמופיעות כאומדן.
• extra_computations – הערך היחיד המותר לפרמטר הזה הוא ADDRESS_DESCRIPTORS. אפשר לקרוא פרטים נוספים במאמר תיאורי כתובות.

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

היפוך של קידוד גיאוגרפי וסינון לפי סוג

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

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

היפוך התשובות עם הקידוד הגיאוגרפי

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

היפוך קודי הסטטוס של הקידוד הגיאוגרפי

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

היפוך הקידוד הגיאוגרפי של קודי OLC

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