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

סקירה כללית

גיאוקוד הוא תהליך המרה של כתובות (כמו ‎1600 Amphitheatre Parkway, Mountain View, CA) לקואורדינטות גיאוגרפיות (כמו קו הרוחב 37.423021 ואורך הרוחב -122.083739), שאפשר להשתמש בהן כדי להציב סמנים או למקם את המפה.

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

אפשר גם להשתמש במקודד הגיאוגרפיה כדי למצוא את הכתובת של מזהה מקום נתון.

ב-Maps JavaScript API יש כיתה של Geocoder שמאפשרת לבצע המרת כתובות לקואורדינטות (geocoding) והמרת קואורדינטות לכתובות (reverse geocoding) באופן דינמי מהקלט של המשתמש. אם במקום זאת רוצים לבצע קידוד גיאוגרפי של כתובות מוכרות, ראו שירות האינטרנט לקידוד גיאוגרפי.

שנתחיל?

לפני שמשתמשים בשירות המרת כתובות לקואורדינטות (geocoding) ב-Maps JavaScript API, צריך לוודא שה-Geocoding API מופעל במסוף Google Cloud, באותו פרויקט שהגדרתם ל-Maps JavaScript API.

כדי להציג את רשימת ממשקי ה-API המופעלים:

  1. נכנסים למסוף Google Cloud.
  2. לוחצים על הלחצן Select a project, בוחרים את אותו פרויקט שהגדרתם ל-Maps JavaScript API ולוחצים על Open.
  3. ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Geocoding API.
  4. אם ה-API מופיע ברשימה, סימן שהכול מוכן. אם ה-API לא מופיע ברשימה, מפעילים אותו:
    1. בחלק העליון של הדף, בוחרים באפשרות ENABLE API כדי להציג את הכרטיסייה Library. לחלופין, בתפריט הימני, לוחצים על ספרייה.
    2. מחפשים את Geocoding API ובוחרים בו מרשימת התוצאות.
    3. לוחצים על הפעלה. בסיום התהליך, Geocoding API יופיע ברשימת ממשקי ה-API במרכז הבקרה.

תמחור ומדיניות

תמחור

למידע על התמחור ועל מדיניות השימוש בשירות המרת כתובות לקואורדינטות (geocoding) ב-JavaScript, קראו את המאמר שימוש וחיוב בנושא Geocoding API.

מדיניות

השימוש שלכם בשירות Geocoding צריך להיות בהתאם למדיניות בנושא Geocoding API.

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

הגישה לשירות המרת כתובות לקואורדינטות (geocoding) היא אסינכרונית, כי Google Maps API צריך לבצע קריאה לשרת חיצוני. לכן, צריך להעביר שיטה של קריאה חוזרת שתתבצע בסיום הבקשה. שיטת הקריאה החוזרת הזו מעבדת את התוצאות. חשוב לדעת שהמקודד הגיאוגרפי עשוי להחזיר יותר מתוצאה אחת.

הגישה לשירות הקידוד הגיאוגרפי של API של מפות Google מתבצעת בקוד באמצעות אובייקט ה-constructor של google.maps.Geocoder. ה-method‏ Geocoder.geocode() יוצר בקשה לשירות הגיאוקודציה, מעביר לו אובייקט GeocoderRequest לינרי שמכיל את מונחי הקלט ו-method של קריאה חוזרת (callback) שיתבצע עם קבלת התשובה.

המילולית של האובייקט GeocoderRequest מכילה את השדות הבאים:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

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

  • address – הכתובת שרוצים להמיר לקואורדינטות.
         או
    location — LatLng (או LatLngLiteral) שעבורו רוצים לקבל את הכתובת הקרובה ביותר קריאה לאנשים. כלי ההמרה מבצע המרת קואורדינטות לכתובות (reverse geocoding). למידע נוסף, אפשר לקרוא את המאמר גיאוקוד הפוכה.
         או
    placeId — מזהה המקום של המקום שעבורו רוצים לקבל את הכתובת הקרובה ביותר שקריאה לאנשים. מידע נוסף על אחזור כתובת של מזהה מקום

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

  • bounds – LatLngBounds שבתוכו תתבצע הטיה של תוצאות הגיאוקוד כך שיוצגו באופן בולט יותר. הפרמטר bounds ישפיע רק על התוצאות מהמקודד הגיאוגרפי, ולא יגביל אותן לחלוטין. בהמשך מפורט מידע נוסף על הטיה של אזור התצוגה .
  • componentRestrictions — משמש להגבלת התוצאות לאזור ספציפי. מידע נוסף על סינון רכיבים מופיע בהמשך.
  • region – קוד האזור, שמוגדר בתג משנה של אזור ב-Unicode בן שתי אותיות (לא מספריות). ברוב המקרים, התגים האלה ממפים ישירות לערכים מוכרים של דומיינים ברמה עליונה עם קוד מדינה (ccTLD) שמכילים שני תווים. הפרמטר region ישפיע רק על התוצאות מהמקודד הגיאוגרפי, ולא יגביל אותן לחלוטין. בהמשך מפורט מידע נוסף על הטיה לפי קוד אזור.
  • extraComputations – הערך היחיד שמותר לפרמטר הזה הוא ADDRESS_DESCRIPTORS. פרטים נוספים זמינים במאמר תיאורי כתובות.
  • fulfillOnZeroResults – ממלאים את ההבטחה בסטטוס ZERO_RESULT בתגובה. יכול להיות שתרצו לעשות זאת כי גם אם לא יהיו תוצאות של גיאוקוד, עדיין יכול להיות שיוחזר שדה נוסף ברמת התגובה. פרטים נוספים זמינים במאמר השלמת משימות ללא תוצאות.

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

שירות הקידוד הגאוגרפי דורש שיטה של קריאה חוזרת (callback) שתתבצע לאחר אחזור התוצאות של השירות. צריך להעביר לשיחה החוזרת שני פרמטרים שיאחסנו את הקוד results ואת הקוד status, לפי הסדר הזה.

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

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

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

השדות האלה מוסברים בהמשך:

  • types[] הוא מערך שמציין את סוג הכתובת של התוצאה שמוחזרת. המערך הזה מכיל קבוצה של אפס תגים או יותר שמזהים את סוג התכונה שמוחזרת בתוצאה. לדוגמה, כתובת גיאוגרפית של 'תל אביב' מחזירה את הערך 'יישוב', שמציין ש'תל אביב' היא עיר, וגם את הערך 'פוליטי', שמציין שהיא ישות פוליטית. בהמשך מפורט מידע נוסף על סוגי כתובות וסוגים של רכיבי כתובת.
  • formatted_address היא מחרוזת שמכילה את הכתובת של המיקום הזה, שקריאה לבני אדם.

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

    הכתובת המעוצבת מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת 'שדרות רוטשילד 11, תל אביב' מורכבת מהרכיבים הבאים: '111' (המספר ברחוב), 'השדרה השמיני' (המסלול), 'תל אביב' (העיר) ו-'תל אביב' (מדינת ארה"ב).

    אין לנתח את הכתובת בפורמט פרוגרמטית. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שנכללים בתגובת ה-API, בנוסף לשדה הכתובת המפורמט.

  • address_components[] הוא מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.

    כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:

    • types[] הוא מערך שמציין את הסוג של רכיב הכתובת. לרשימת הסוגים הנתמכים
    • long_name הוא הטקסט המלא או התיאור של רכיב הכתובת כפי שהוחזר על ידי המקודד הגיאוגרפי.
    • short_name הוא שם טקסט מקוצר של רכיב הכתובת, אם יש כזה. לדוגמה, רכיב הכתובת של מדינת אלסקה עשוי להכיל long_name של "Alaska" ו-short_name של "AK" באמצעות קיצור הדואר בן 2 האותיות.

    שימו לב לעובדות הבאות לגבי המערך address_components[]:

    • מערך רכיבי הכתובות עשוי להכיל יותר רכיבים מאשר formatted_address.
    • המערך לא כולל בהכרח את כל הישויות הפוליטיות שמכילות כתובת, מלבד אלה שכלולות ב-formatted_address. כדי לאחזר את כל הישויות הפוליטיות שמכילות כתובת ספציפית, צריך להשתמש בקידוד גיאוגרפי הפוך ולהעביר את קו הרוחב/קו האורך של הכתובת כפרמטר לבקשה.
    • לא בטוח שהפורמט של התשובה יהיה זהה בכל הבקשות. באופן ספציפי, מספר הaddress_components משתנה בהתאם לכתובת המבוקשת, והוא עשוי להשתנות עם הזמן עבור אותה כתובת. רכיב יכול לשנות את המיקום במערך. סוג הרכיב יכול להשתנות. יכול להיות שרכיב מסוים יהיה חסר בתשובה מאוחרת יותר.

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

  • partial_match מציין שהקואורדינטות לא החזירו התאמה מדויקת לבקשה המקורית, למרות שהוא הצליח להתאים חלק מהכתובת המבוקשת. כדאי לבדוק את הבקשה המקורית עם שגיאות כתיב ו/או כתובת חלקית.

    לרוב מתרחשות התאמות חלקיות לכתובות רחובות שלא קיימות ברשות המוניציפאלית שמעבירים בבקשה. יכול להיות שהמערכת תחזיר גם התאמות חלקיות כאשר הבקשה תואמת לשני מיקומים או יותר באותו רשות מוניציפאלית. לדוגמה, הטקסט "Hillpar St, Bristol, UK" יחזיר התאמה חלקית גם לרחוב Henry ול-Henrietta Street. שימו לב שאם הבקשה כוללת רכיב כתובת עם שגיאות איות, שירות הקידוד הגיאוגרפי עשוי להציע כתובת חלופית. הצעות שמופעלות באופן הזה יסומנו גם כהתאמה חלקית.

  • place_id הוא מזהה ייחודי של מקום, שאפשר להשתמש בו עם ממשקי Google API אחרים. לדוגמה, אפשר להשתמש ב-place_id עם הספרייה של Google Places API כדי לקבל פרטים על עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות של משתמשים ועוד. סקירה כללית על מזהי מקומות
  • postcode_localities[] הוא מערך שמציין את כל היישובים שמכיל המיקוד, והוא מופיע רק כשהתוצאה היא מיקוד שמכיל כמה יישובים.

  • geometry מכיל את המידע הבא:

    • השדה location מכיל את הערך של קו הרוחב וקו האורך לאחר הגיאוקודציה. שימו לב שהמיקום הזה מוחזר כאובייקט LatLng, ולא כמחרוזת בפורמט.
    • location_type שומר נתונים נוספים על המיקום שצוין. הערכים הבאים נתמכים:
      • הערך ROOFTOP מציין שהתוצאה שמוחזרת משקפת כתובת גיאוגרפית מדויקת.
      • הערך RANGE_INTERPOLATED מציין שהתוצאה שמוחזרת משקפת הערכה (בדרך כלל על דרך) שעבר תהליך אינטרפולציה בין שתי נקודות מדויקות (למשל צמתים). בדרך כלל, תוצאות אינטרפולציה מוחזרות כשאין קואורדינטות גיאוגרפיות של גגות עבור כתובת רחוב.
      • הערך GEOMETRIC_CENTER מציין שהתוצאה שמוחזרת היא המרכז הגיאומטרי של תוצאה כמו קו מרובע (למשל, רחוב) או פוליגון (אזור).
      • APPROXIMATE מציין שהתוצאה שחוזרת היא משוערת.

    • viewport שומר את אזור התצוגה המומלץ לתוצאה שהוחזרה.
    • המשתנה bounds (אופציונלי, מוחזר) מאחסן את הערך של LatLngBounds, שיכול להכיל את התוצאה המוחזרת במלואה. לתשומת ליבכם: יכול להיות שהגבולות האלה לא יהיו תואמים למסך המכוון המומלץ. (לדוגמה, סן פרנסיסקו כוללת את איי פארלון, שהם חלק מהעיר מבחינה טכנית, אבל אסור להחזיר אותם באזור התצוגה).

כתובות מוחזרות על ידי המקודד הגיאוגרפי באמצעות הגדרת השפה המועדפת של הדפדפן, או השפה שצוינה כשטוענים את ה-JavaScript של ה-API באמצעות הפרמטר language. (מידע נוסף זמין במאמר לוקליזציה).

סוגי כתובות וסוגי רכיבי כתובות

המערך types[] ב-GeocoderResult מציין את סוג הכתובת. אפשר גם להחזיר את המערך types[] בתוך GeocoderAddressComponent כדי לציין את הסוג של רכיב הכתובת הספציפי. לכתובות שמוחזרות על ידי המקודד הגיאוגרפי יכולים להיות כמה סוגים, והסוגים האלה יכולים להיחשב כתגים. לדוגמה, ערים רבות מסומנות בתגים מסוג political ו-locality.

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

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

רשימה ריקה של סוגים מציינת שאין סוגים ידועים לרכיב הכתובת הספציפי, לדוגמה, Lieu-dit בצרפת.

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

הערה: זוהי רשימה חלקית בלבד, והיא עשויה להשתנות.

  • floor מציין את הקומה בכתובת של בניין.
  • establishment מציין בדרך כלל מקום שעדיין לא סווג בקטגוריה.
  • landmark מציין מקום קרוב שמשמש כהפניה, כדי לעזור בניווט.
  • point_of_interest מציין נקודת עניין עם שם.
  • parking מציין חניון או מגרש חניה.
  • post_box מציין תיבת דואר ספציפית.
  • postal_town מציין קיבוץ של אזורים גיאוגרפיים, כמו locality ו-sublocality, שמשמשים לכתובות למשלוח דואר במדינות מסוימות.
  • room מציין את החדר בכתובת בניין.
  • street_number מציין את מספר הרחוב המדויק.
  • bus_station, train_station ו-transit_station מציינים את המיקום של תחנת אוטובוס, רכבת או תחבורה ציבורית.

קודי סטטוס

קוד status עשוי להחזיר אחד מהערכים הבאים:

  • "OK" מציין שלא התרחשו שגיאות; הכתובת עברה ניתוח בהצלחה, והוחזר לפחות קואורדינטות אחד.
  • "ZERO_RESULTS" מציין שהקידוד הגיאוגרפי הצליח אבל לא החזיר תוצאות. מצב כזה יכול לקרות אם הועבר באמצעות הקואורדינטות address שלא קיימים.
  • "OVER_QUERY_LIMIT" מציין שחרגתם מהמכסה.
  • "REQUEST_DENIED" מציין שהבקשה שלך נדחתה. דף האינטרנט לא רשאי להשתמש במקודד הגיאוגרפיה.
  • בדרך כלל, הערך "INVALID_REQUEST" מציין שהשאילתה (address, components או latlng) חסרה.
  • "UNKNOWN_ERROR" מציין שלא ניתן היה לעבד את הבקשה בגלל שגיאה בחיבור לשרת. אם תנסו שוב, יכול להיות שהבקשה תאושר.
  • הערך "ERROR" מציין שפג הזמן הקצוב לבקשת ההתחברות או שהיתה בעיה ביצירת קשר עם שרתי Google. אם תנסו שוב, יכול להיות שהבקשה תאושר.

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

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

להצגת דוגמה

הטיה של אזור התצוגה

אפשר להורות לשירות הגיאוקודציה להעדיף תוצאות בתוך חלון תצוגה נתון (שמוצג כתיבת מלבנית). כדי לעשות זאת, מגדירים את הפרמטר bounds בתוך ליטרל האובייקט GeocoderRequest כדי להגדיר את הגבולות של אזור התצוגה הזה. חשוב לזכור שהטיה רק מעדיפה תוצאות בתוך הגבולות. אם יש תוצאות רלוונטיות יותר מחוץ לגבולות האלה, הן עשויות להיכלל.

לדוגמה, כשמעבדים את המיקום 'Winnetka' במערכת לחישוב קואורדינטות גיאוגרפיות, בדרך כלל מקבלים את הפרבר הזה של שיקגו:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

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

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

הטיה של קוד האזור

אפשר להגדיר את שירות המיפוי הגיאוגרפית כך שיחזיר תוצאות עם הטיה לאזור מסוים באופן מפורש באמצעות הפרמטר region. הפרמטר הזה מקבל קוד אזור, שמצוין בתג משנה של אזור ב-Unicode בן שני תווים (לא מספריים). התגים האלה ממופים ישירות לערכים מוכרים של דומיינים ברמה עליונה עם קוד מדינה (ccTLD) שמכילים שני תווים, כמו 'uk' ב-'co.uk', לדוגמה. במקרים מסוימים, התג region תומך גם בקודים של ISO-3166-1, שלפעמים שונים מהערכים של ccTLD (לדוגמה, 'GB' עבור 'בריטניה הגדולה').

כשמשתמשים בפרמטר region:

  • יש לציין רק מדינה או אזור אחד. המערכת מתעלמת מכמה ערכים, ויכול להיות שהדבר יוביל לבקשה שנכשלה.
  • יש להשתמש רק בתגי משנה של אזורים עם שני תווים (בפורמט Unicode CLDR). כל הקלט האחר יגרום לשגיאות.
  • המערכת תומכת רק במדינות ובאזורים שמפורטים בפרטי הכיסוי של פלטפורמת מפות Google.

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

לדוגמה, כתובת גיאוגרפית של 'טולדו' מחזירה את התוצאה הזו, כי הדומיין שמוגדר כברירת מחדל לשירות הגיאוקודציה הוא ארצות הברית:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

כתובת גיאוגרפית של 'Toledo' עם השדה region מוגדר ל-'es' (ספרד) תחזיר את העיר בספרד:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

סינון רכיבים

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

המקודד הגיאוגרפי מחזיר רק את התוצאות שתואמות לכל המסננים של הרכיבים. כלומר, היא מעריכה את מפרטי המסנן כ-AND ולא כ-OR.

מסנן רכיבים מורכב מאחד או יותר מהפריטים הבאים:

  • route תואם לשם ארוך או קצר של נתיב.
  • locality מתאים לסוגים של יישוב ורובע.
  • הערך administrativeArea תואם לכל הרמות של האזור המנהלי.
  • postalCode תואם למספרי מיקוד ולקידומות של מספרי מיקוד.
  • הערך country תואם לשם מדינה או לקוד מדינה של ISO 3166-1 בן שתי אותיות. הערה: ה-API פועל בהתאם לתקן ISO להגדרת מדינות, והסינון פועל בצורה הטובה ביותר כשמשתמשים בקוד ה-ISO התואם של המדינה.

בדוגמה הבאה מוצג שימוש בפרמטר componentRestrictions כדי לסנן לפי country ו-postalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

מילוי הזמנות ללא תוצאות

בהמרת קואורדינטות לכתובות, כברירת מחדל ההתחייבות מופיעה ב-status=ZERO_RESULTS. עם זאת, יכול להיות שהשדות הנוספים ברמת התשובה, plus_code ו-address_descriptor, עדיין יאוכלסו במקרה כזה. אם צוין True לפרמטר fulfillOnZeroResults, יאוכלס במקרה הזה. אם הערך true מסופק לפרמטר fulfillOnZeroResults, ההתחייבות לא תבוטל וניתן יהיה לגשת לשדות הנוספים האלה מההתחייבות, אם הם קיימים.

בדוגמה הבאה מוצגת ההתנהגות הזו עבור קו הרוחב/קו האורך באנטארקטיקה. גם אם אין תוצאות של המרה הפוכה של כתובת לקואורדינטות, עדיין נוכל להדפיס את קוד ה-Plus בהבטחה אם נגדיר את fulfillOnZeroResults=true. 

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

מתארי כתובות

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

אפשר להפעיל את מאפייני הכתובת באמצעות הפרמטר extraComputations. כדי לקבל תיאורים של כתובות בתגובה, צריך לכלול את extra_computations=ADDRESS_DESCRIPTORS בבקשת גיאוקוד, בבקשת המרת קואורדינטות לכתובות (reverse geocoding) או בבקשת גיאוקוד של מקומות.

דוגמה להמרה של מיקומים לקואורדינטות

השאילתה הבאה מכילה את הכתובת של מקום בדלהי.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

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

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

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

דוגמה לתיאור כתובת

דוגמה ל-address_descriptor:

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

יש שני מערכי נתונים בכל אובייקט address_descriptor: landmarks ו-areas. המערך landmarks מכיל עד 5 תוצאות שמדורגות לפי רמת הרלוונטיות, תוך התחשבות בקירבה לקואורדינטות המבוקשות, בשכיחות של ציון הדרך ובמידת החשיפה שלו. כל תוצאה של ציון דרך מכילה את הערכים הבאים:

  • place_id הוא מזהה המקום של תוצאת ציוני הדרך. סקירה כללית על מזהי מקומות
  • display_name הוא השם המוצג של ציון הדרך, והוא מכיל את language_code ואת text.
  • straight_line_distance_meters הוא המרחק מנקודה לנקודה במטרים בין קואורדינטת הקלט לתוצאה של ציוני הדרך.
  • travel_distance_meters הוא המרחק במטרים שנסעו באמצעות רשת הכבישים (תוך התעלמות ממגבלות הכבישים) בין קואורדינטת הקלט לתוצאה של ציוני הדרך.
  • spatial_relationship הוא הקשר המשוער בין קואורדינטת הקלט לבין תוצאת ציוני הדרך:
    • "NEAR" הוא קשר ברירת המחדל כשאף אחת מהאפשרויות הבאות לא רלוונטית.
    • "WITHIN" כאשר קואורדינטת הקלט נכללת בגבולות המבנה שמשויך לנקודת הציון.
    • "BESIDE" כאשר קואורדינטת הקלט נמצאת בסמוך ישירות לנקודת הציון או לנקודת הגישה של נקודת הציון.
    • "ACROSS_THE_ROAD" כשקואורדינטת הקלט נמצאת ממש מול ציון הדרך בצד השני של המסלול.
    • "DOWN_THE_ROAD" כשקואורדינטת הקלט נמצאת באותו מסלול כמו ציון הדרך, אבל לא "BESIDES" או "ACROSS_THE_ROAD".
    • "AROUND_THE_CORNER" כאשר קואורדינטת הקלט נמצאת לאורך מסלול אנכי כמו ציון הדרך (מוגבלת לפנייה אחת).
    • "BEHIND" כאשר קואורדינטת הקלט קרובה מבחינה מרחבית לנקודת הציון, אבל רחוקה מנקודת הגישה שלה.
  • types הם סוגי המקומות של ציון הדרך.

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

  • place_id הוא מזהה המקום של תוצאת האזורים. סקירה כללית על מזהי מקומות
  • display_name הוא השם המוצג של האזור, והוא מכיל את language_code ואת text.
  • containment הוא יחס ההכללה המשוער בין קואורדינטת הקלט לבין התוצאה של האזורים:
    • "NEAR" הוא קשר ברירת המחדל כשאף אחת מהאפשרויות הבאות לא רלוונטית.
    • "WITHIN" כאשר קואורדינטת הקלט קרובה למרכז האזור.
    • "OUTSKIRTS" כשקואורדינטת הקלט קרובה לקצה האזור.

הכיסוי של תיאור הכתובת

מתארי הכתובות נמצאים ב-GA בהודו. השימוש בתיאורי כתובות בהודו לא כרוך בעלות נוספת, והשימוש מכוסה על ידי מק"ט Essentials של שירותי גיאוקוד (הודו) הקיים.

משוב

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

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

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

במקום לספק address טקסטואלי, צריך לספק פרמטר location עם זוג קו הרוחב/קו האורך מופרדים בפסיקים.

בדוגמה הבאה מתבצע קידוד גיאוגרפי של ערך קו רוחב/קו אורך והמיקום הזה ממורכז במפה, תוך הצגת חלון מידע עם הכתובת בפורמט:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
להצגת דוגמה

ניסיון של דוגמה

שימו לב שבדוגמה הקודמת הצגנו את התוצאה הראשונה על ידי בחירה באפשרות results[0]. לרוב, מקודד המיקום ההפוך מחזיר יותר מתוצאה אחת. כתובות שהומרו לקואורדינטות גיאוגרפיות הן לא רק כתובות למשלוח דואר, אלא כל דרך למתן שם למיקום לפי מיקום גיאוגרפי. לדוגמה, כשמבצעים גיאוקוד של נקודה בעיר שיקגו, יכול להיות שהנקודה שתתקבל תסומן ככתובת רחוב, כעיר (שיקגו), כמדינה (אילינוי) או כמדינה (ארצות הברית). כל הכתובות הן כתובות למקודד הגיאוגרפית. המרת הקואורדינטות לכתובות מחזירה את כל התוצאות האלה.

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

דוגמה לרשימה של כתובות שתתקבל מהשאילתה שלמעלה: 

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

הכתובות מוצגות לפי סדר ההתאמה הטובה ביותר עד לפחות טובה. בדרך כלל, הכתובת המדויקת יותר היא התוצאה הבולטת ביותר, כמו במקרה הזה. הערה: אנחנו מחזירים סוגים שונים של כתובות, החל מהרחוב הספציפי ביותר ועד לישויות פוליטיות פחות ספציפיות כמו שכונות, ערים, מחוזות, מדינות וכו'. אם רוצים להתאים כתובת כללית יותר, מומלץ לבדוק את השדה results[].types.

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

אחזור כתובת של מזהה מקום

מציינים placeId כדי למצוא את הכתובת של מזהה מקום נתון. מזהה המקום הוא מזהה ייחודי שאפשר להשתמש בו בממשקי Google API אחרים. לדוגמה, אפשר לספק את הערך placeId שמוחזר על ידי Roads API כדי לקבל את הכתובת של נקודה שמוצמדת. למידע נוסף על מזהי מקומות, ראו סקירה כללית על מזהי מקומות.

כשמציינים placeId, הבקשה לא יכולה לכלול אף אחד מהשדות הבאים:

  • address
  • latLng
  • location
  • componentRestrictions

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

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
להצגת דוגמה

ניסיון של דוגמה