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

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

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

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

• 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 מציין את הישות הפוליטית הלאומית, והוא בדרך כלל סוג ההזמנה הגבוה ביותר שהוחזר על ידי ה-Geocoder.
  • 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 Codes כתחליף ל- של רחובות במקומות שבהם הן אינן קיימות (כאשר הבניינים אינם ממוספרים, אין שמות של רחובות). פרטים נוספים בכתובת https://plus.codes לקבלת פרטים.
  • postal_code מציין מיקוד שמשמש לטיפול במיקוד בתוך המדינה.
  • natural_feature מציין ישות טבעית בולטת.
  • airport מציין שדה תעופה.
  • park מציין פארק בעל שם.
  • point_of_interest מציין נקודת עניין עם שם. בדרך כלל, נקודות העניין האלה הן ישויות מקומיות בולטות שלא מופיעות בקלות בקטגוריה אחרת, למשל 'בניין האמפייר סטייט' או "מגדל אייפל".
• location_type - מסנן מסוג אחד או יותר של מיקומים, שמופרדות בקו אנכי (|). אם הפרמטר מכיל locations, ה-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

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

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

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

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

.