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

מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

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

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

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

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

המרת הקואורדינטות לכתובות (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)

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

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

השדה "status" באובייקט התגובה של המרת הכתובות לקואורדינטות מכיל את סטטוס הבקשה, ויכול להכיל מידע על תוצאות ניפוי הבאגים שיעזור לכם להבין למה המרת הקואורדינטות לכתובות לא עובדת. השדה "status" יכול להכיל את הערכים הבאים:

  • "OK" מציין שלא אירעו שגיאות ושהוחזרה כתובת אחת לפחות.
  • "ZERO_RESULTS" מציין שהמרת הקואורדינטות לכתובות (reverse geocoding) בוצעה בהצלחה אבל לא הוחזרו תוצאות. זה יכול לקרות אם לכלי להמרת כתובות לקואורדינטות (geocoder) הועבר latlng במיקום מרוחק.
  • "OVER_QUERY_LIMIT" מציין שחרגתם מהמכסה.
  • ‫"REQUEST_DENIED" מציין שהבקשה נדחתה. יכול להיות שהסיבה היא שהבקשה כוללת פרמטר result_type או location_type אבל לא כוללת מפתח API.
  • הסטטוס "INVALID_REQUEST" בדרך כלל מציין אחת מהאפשרויות הבאות:
    • השאילתה (address,‏ components או latlng) חסרה.
    • הוזן ערך לא תקין בשדה result_type או location_type.
  • ‫"UNKNOWN_ERROR" מציין שלא ניתן היה לעבד את הבקשה בגלל שגיאה בחיבור לשרת. יכול להיות שהבקשה תצליח אם תנסו שוב.

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

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