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

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

סקירה כללית

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

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

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

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

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

תמחור

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

מדיניות

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

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

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

רה

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הכתובות מוחזרות על ידי הגיאוקודר באמצעות הגדרת השפה המועדפת של הדפדפן, או השפה שצוינה בזמן טעינת ה-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" מציין שהגיאו-קוד נוצר בהצלחה אבל לא הוחזרו תוצאות. יכול להיות שהבעיה הזו מתרחשת אם הועבר לכלי להמרת כתובות לקואורדינטות (geocoder) address שלא קיים.
  • הערך "OVER_QUERY_LIMIT" מציין שחרגתם מהמכסה.
  • ‫"REQUEST_DENIED" מציין שהבקשה שלך נדחתה. לאתר האינטרנט אין הרשאה להשתמש בכלי להמרת כתובות לקואורדינטות (geocoder).
  • קוד השגיאה "INVALID_REQUEST" מציין בדרך כלל שהשאילתה (address, components או latlng) חסרה.
  • "UNKNOWN_ERROR" מציין שלא ניתן היה לעבד את הבקשה בגלל שגיאה בחיבור לשרת. יכול להיות שהבקשה תצליח אם תנסו שוב.
  • ‫"ERROR" מציין שפג הזמן הקצוב לתגובה לבקשה או שהייתה בעיה ביצירת קשר עם שרתי Google. יכול להיות שהבקשה תצליח אם תנסו שוב.

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

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

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

לדוגמה מלאה

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

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

לדוגמה, המרת כתובות לקואורדינטות (geocoding) של 'וינטקה' בדרך כלל מחזיר את הפרבר הזה של שיקגו:

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

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

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

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

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

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

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

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

לדוגמה, המרת כתובות לקואורדינטות (geocoding) של Toledo תחזיר את התוצאה הזו, כי דומיין ברירת המחדל של שירות ההמרת כתובות לקואורדינטות (geocoding) מוגדר לארצות הברית:

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

סינון רכיבים

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה ל-address_descriptor:

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

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

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

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

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

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

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

משוב

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

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

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

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

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

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

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

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

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

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