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

הערה: ספריות בצד השרת
מפתחים באזור הכלכלי האירופי (EEA)

סקירה כללית

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

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

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

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

שנתחיל?

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

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

תמחור

מידע על מדיניות התמחור והשימוש בשירות JavaScript Geocoding זמין במאמר בנושא שימוש וחיוב ב-Geocoding API.

מדיניות

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

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

הגישה לשירות Geocoding היא אסינכרונית, ונדרשת קריאה לשרת חיצוני. מסיבה זו, השיטה geocode מחזירה הבטחה שמושלמת עם סיום הבקשה. אחרי שהבעיה תיפתר, תוכלו להשתמש ב-.then() או ב-await כדי לטפל בתגובה.

רה

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

הליטרל של האובייקט 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)

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

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

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

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

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

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

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

  • המידע הבא מופיע ב-geometry:

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

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

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

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

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

יכולים להיות כמה סוגים של כתובות. אפשר להתייחס לסוגים האלה כאל 'תגים'. לדוגמה, ערים רבות מתויגות בסוגים political ו-locality.

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

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

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

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

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

TypeScript

async function geocode(request: google.maps.GeocoderRequest) {
    clear();

    geocoder
        .geocode(request)
        .then((result) => {
            const { results } = result;
            innerMap.setCenter(results[0].geometry.location);
            marker.position = new google.maps.LatLng(results[0].geometry.location);
            mapElement.append(marker);
            responseDiv.style.display = 'block';
            response.innerText = JSON.stringify(result, null, 2);
            return results;
        })
        .catch((e) => {
            alert('Geocode was not successful for the following reason: ' + e);
        });
}
index.ts

JavaScript

async function geocode(request) {
    clear();
    geocoder
        .geocode(request)
        .then((result) => {
        const { results } = result;
        innerMap.setCenter(results[0].geometry.location);
        marker.position = new google.maps.LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        response.innerText = JSON.stringify(result, null, 2);
        return results;
    })
        .catch((e) => {
        alert('Geocode was not successful for the following reason: ' + e);
    });
}
index.js

לדוגמה מלאה

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

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

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

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

אפשר לשלוח בקשות לגיאו-קידוד לכל דומיין שבו אפליקציית מפות 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:

async function codeAddress(request: google.maps.GeocoderRequest) {
    clear();
    geocoder.geocode({
        componentRestrictions: {
            country: 'AU',
            postalCode: '2000'
        }
    })
    .then((result) => {
        const { results } = result;
        innerMap.setCenter(results[0].geometry.location);
        let marker = new google.maps.marker.AdvancedMarkerElement({
            map: innerMap,
            position: results[0].geometry.location
        });
    })
    .catch((e) => {
        alert('Geocode was not successful for the following reason: ' + e);
    });
};

השלמת הזמנה כשאין תוצאות

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

הנה דוגמה להתנהגות הזו עבור קו רוחב/קו אורך באנטארקטיקה. גם אם אין תוצאות של המרת קואורדינטות לכתובות (reverse geocoding), עדיין אפשר להדפיס את קוד הפלוס באובייקט promise אם מגדירים את 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: ${error}`);
    });
}

תיאורי כתובות

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

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

דוגמה לגיאו-קידוד של מקומות

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

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

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

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

    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 Descriptor Coverage

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

משוב

התכונה הזו זמינה בכל האזורים. הוא זמין ב-GA בהודו ובשלב ההשקה הניסיונית של טרום-GA בכל שאר האזורים. נשמח לקבל משוב:

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

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

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

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

TypeScript

let marker;

async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary(
                'maps'
            ) as Promise<google.maps.MapsLibrary>,
            google.maps.importLibrary(
                'geocoding'
            ) as Promise<google.maps.GeocodingLibrary>,
            google.maps.importLibrary(
                'marker'
            ) as Promise<google.maps.MarkerLibrary>,
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng') as HTMLInputElement;

    // Get the submit button.
    const submitButton = document.getElementById('submit') as HTMLElement;

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
        mapTypeControl: false,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    marker.anchorTop = "40px";

    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}

async 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]) {
                marker.position = latlng;
                map.setCenter(latlng);
                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));
}

initMap();
index.ts

JavaScript

let marker;
async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('marker'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng');
    // Get the submit button.
    const submitButton = document.getElementById('submit');
    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
        mapTypeControl: false,
    });
    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });
    marker.anchorTop = "40px";
    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();
    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}
async 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]) {
            marker.position = latlng;
            map.setCenter(latlng);
            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));
}
initMap();
index.js

CSS

/*
* Always set the map height explicitly to define the size of the div element
* that contains the map.
*/
gmp-map {
    height: 100%;
}

/*
* Optional: Makes the sample page fill the window.
*/
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
    font-family: Roboto, sans-serif;
}

#floating-panel {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 10px;
    font-family: Roboto, sans-serif;
    font-size: 1rem;
}

#latlng {
    width: 100%;
    font-family: Roboto, sans-serif;
    font-size: 1rem;
    margin-bottom: 4px;
}

#submit {
    font-size: 1rem;
}
style.css

HTML

<html>
    <head>
        <title>Reverse Geocoding</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
   ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly" });</script>
    </head>
    <body>
        <gmp-map center="0.714224, -73.961452" zoom="8" map-id="DEMO_MAP_ID">
            <div id="floating-panel" slot="control-block-start-inline-start">
                <p>
                    Click the map to reverse geocode, or add your own
                    coordinates.
                </p>
                <input
                    id="latlng"
                    type="text"
                    value="40.714224, -73.961452" /><br />
                <input id="submit" type="button" value="Reverse Geocode" />
            </div>
        </gmp-map>
    </body>
</html>
index.html
להצגת דוגמה

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

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

כשמספקים placeId, הבקשה לא יכולה להכיל את השדות הבאים:

  • address
  • latLng
  • location
  • componentRestrictions

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

TypeScript

// Initialize the map.
async function initMap(): Promise<void> {
  await Promise.all([
    google.maps.importLibrary("maps"),
    google.maps.importLibrary("geocoding"),
    google.maps.importLibrary("marker"),
  ]);

  const mapElement = document.querySelector("gmp-map") as google.maps.MapElement;
  const innerMap = mapElement.innerMap;
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

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

// This function is called when the user clicks the UI button.
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.AdvancedMarkerElement({
          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));
}

initMap();
index.ts

JavaScript

// Initialize the map.
async function initMap() {
    await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("geocoding"),
        google.maps.importLibrary("marker"),
    ]);
    const mapElement = document.querySelector("gmp-map");
    const innerMap = mapElement.innerMap;
    const geocoder = new google.maps.Geocoder();
    const infowindow = new google.maps.InfoWindow();
    document.getElementById("submit").addEventListener("click", () => {
        geocodePlaceId(geocoder, innerMap, infowindow);
    });
}
// This function is called when the user clicks the UI button.
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.AdvancedMarkerElement({
                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));
}
initMap();
index.js
להצגת דוגמה

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