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

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

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

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

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

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

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

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

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

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

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