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

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

תמחור

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

מדיניות

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

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

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

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

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

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

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

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

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);
    }
  });
}

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

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

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

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

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

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