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

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

תמחור

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

מדיניות

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

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

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

כדי לגשת לשירות הקידוד הגאוגרפי של Google Maps API בקוד, משתמשים באובייקט ה-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) שתתבצע לאחר אחזור התוצאות של המקודד הגאוגרפי. הקריאה החוזרת (callback) הזו צריכה להעביר שני פרמטרים כדי להחזיק את הקוד results ואת הקוד status, בסדר הזה.

תוצאות הקידוד הגיאוגרפי

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

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

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

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

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

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

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

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

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

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

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

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

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

function addressDescriptorPlaceIdLookup() {
  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);
    }
  });
}

דוגמה בקידוד גיאוגרפי הפוך

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

    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" כשקואורדינטת הקלט קרובה לקצה האזור.

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

התכונה הזו זמינה רק במדינות נבחרות.

זוהי תכונה בתצוגה מקדימה ונשמח לקבל משוב. אפשר לשלוח לנו אימייל לכתובת address-descriptors-feedback@google.com.

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

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

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

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

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

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

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