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

סקירה כללית

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

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

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

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

תחילת העבודה

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

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

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

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

תמחור

ב-16 ביולי 2018 נכנסה לתוקף תוכנית התמחור החדשה 'תשלום לפי שימוש' עבור מפות Google, מסלולים ומקומות. למידע נוסף על מגבלות התמחור והשימוש החדשות בשירות הקידוד הגיאוגרפי של JavaScript, קראו את המאמר שימוש וחיוב ב-Geocoding API.

כללי מדיניות

השימוש בשירות הקידוד הגיאוגרפי חייב להיות בהתאם למדיניות שמתוארת ב-Geocoding API.

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

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

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

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

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

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

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

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

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

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

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

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

    הכתובת בפורמט הנכון מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת " 111 8th Avenue, New York, NY" מורכבת מהרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (המסלול), "New York" (העיר) ו-"NY" (מדינת ארה"ב).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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"
}

קוד גיאוגרפי של "טולדו" שבו השדה 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);
  }
});
}

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

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

במקום לציין 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;

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;
להצגת דוגמה

רוצה לנסות דוגמה?

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

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

הנה דוגמה לרשימת הכתובות שהשאילתה שלמעלה עשויה להחזיר:

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.

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

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

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

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;
להצגת דוגמה

רוצה לנסות דוגמה?