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

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

סקירה כללית

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

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

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

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

שנתחיל?

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

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

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

תמחור

כדי לקבל מידע על מדיניות התמחור והשימוש בשירות המרת הכתובות לקואורדינטות ב-JavaScript, קראו את המאמר שימוש וחיוב בנושא Geocoding API.

מדיניות

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

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

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

re

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

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

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

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

  • ‫address – הכתובת שרוצים להמיר לקואורדינטות.
         או
    location — LatLng (או LatLngLiteral) שעבורם רוצים לקבל את הכתובת הקרובה ביותר שקריאה לאנשים. הכלי להמרת כתובות לקואורדינטות (geocoder) מבצע המרה של קואורדינטות לכתובות (reverse geocoding). מידע נוסף זמין במאמר המרת קואורדינטות לכתובות (reverse geocoding).
         או
    placeId – מזהה המקום של המקום שרוצים לקבל את הכתובת הקריאה לאנשים שהכי קרובה אליו. מידע נוסף על אחזור כתובת של מזהה מקום

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

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

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

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

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

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

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

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

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

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

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

סוגי כתובות וסוגי רכיבים של כתובות

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

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

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

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

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

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

TypeScript

async function geocode(request: google.maps.GeocoderRequest) {
    clear();
    const { LatLng } = await google.maps.importLibrary('core');

    try {
        const response = await geocoder.geocode(request);
        const { results } = response;

        innerMap.setCenter(results[0].geometry.location);
        marker.position = new LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        responsePre.innerText = JSON.stringify(response, null, 2);
        return results;
    } catch (e) {
        alert(
            'Geocode was not successful for the following reason: ' + String(e)
        );
    }
}

JavaScript

async function geocode(request) {
    clear();
    const { LatLng } = await google.maps.importLibrary('core');

    try {
        const response = await geocoder.geocode(request);
        const { results } = response;

        innerMap.setCenter(results[0].geometry.location);
        marker.position = new LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        responsePre.innerText = JSON.stringify(response, null, 2);
        return results;
    } catch (e) {
        alert(
            'Geocode was not successful for the following reason: ' + String(e)
        );
    }
}

הצג את הדוגמה הפתורה.

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

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

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

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

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

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

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

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

לדוגמה, קואורדינטות של "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"
}

אם תמירו את הכתובת "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"
}

סינון רכיבים

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

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

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

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

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

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

משוב

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

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

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

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

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

TypeScript

let marker: google.maps.marker.AdvancedMarkerElement;

async function init() {
    //  Request the needed libraries.
    const [{ 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') as HTMLInputElement;

    // 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', () => {
        void geocodeLatLng(geocoder, innerMap, infoWindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        if (event.latLng) {
            latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
            void geocodeLatLng(geocoder, innerMap, infoWindow);
        }
    });

    // Make an initial request upon loading.
    void 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]),
    };

    try {
        const { results } = await geocoder.geocode({ location: latlng });

        if (results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infoWindow.setContent(results[0].formatted_address);
            infoWindow.open(map, marker);
        } else {
            window.alert('No results found');
        }
    } catch (e) {
        window.alert('Geocoder failed due to: ' + String(e));
    }
}

void init();

JavaScript

let marker;

async function init() {
    //  Request the needed libraries.
    const [{ 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', () => {
        void geocodeLatLng(geocoder, innerMap, infoWindow);
    });

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

    // Make an initial request upon loading.
    void 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]),
    };

    try {
        const { results } = await geocoder.geocode({ location: latlng });

        if (results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infoWindow.setContent(results[0].formatted_address);
            infoWindow.open(map, marker);
        } else {
            window.alert('No results found');
        }
    } catch (e) {
        window.alert('Geocoder failed due to: ' + String(e));
    }
}

void init();

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

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </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>
להצגת דוגמה

שימו לב שבדוגמה הקודמת הצגנו את התוצאה הראשונה על ידי בחירה באפשרות results[0]. המרת קואורדינטות לכתובות (reverse 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.

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

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

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

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

  • address
  • latLng
  • location
  • componentRestrictions

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

TypeScript

// Initialize the map.
async function init(): Promise<void> {
    const [{ Geocoder }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;
    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    document.getElementById('submit')!.addEventListener('click', () => {
        void geocodePlaceId(geocoder, innerMap, infoWindow);
    });
}

// This function is called when the user clicks the UI button.
async function geocodePlaceId(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infoWindow: google.maps.InfoWindow
) {
    const placeId = (document.getElementById('place-id') as HTMLInputElement)
        .value;

    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    const { results } = await geocoder.geocode({ placeId });
    if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new AdvancedMarkerElement({
            map,
            position: results[0].geometry.location,
        });

        infoWindow.setContent(results[0].formatted_address);
        infoWindow.open(map, marker);
    } else {
        window.alert('No results found');
    }
}

void init();

JavaScript

// Initialize the map.
async function init() {
    const [{ Geocoder }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    document.getElementById('submit').addEventListener('click', () => {
        void geocodePlaceId(geocoder, innerMap, infoWindow);
    });
}

// This function is called when the user clicks the UI button.
async function geocodePlaceId(geocoder, map, infoWindow) {
    const placeId = document.getElementById('place-id').value;

    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    const { results } = await geocoder.geocode({ placeId });
    if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new AdvancedMarkerElement({
            map,
            position: results[0].geometry.location,
        });

        infoWindow.setContent(results[0].formatted_address);
        infoWindow.open(map, marker);
    } else {
        window.alert('No results found');
    }
}

void init();
להצגת דוגמה

בחירת ה-API המתאים לכתובות או לקואורדינטות

הרחיבו את הקטע הבא כדי להשוות בין google.maps.Geocoder לבין ממשקי API אחרים של Google Maps Platform, למשימות נפוצות שקשורות לכתובות ולקואורדינטות:

השוואה בין Geocoder לבין ממשקי API אחרים של Google Maps Platform

המטרה של המפתח ה-API או השיטה המומלצים מתי להשתמש?
המרת כתובת מלאה לקואורדינטות של LatLng (המרה רגילה של כתובות לקואורדינטות) geocoder.geocode({ address }) (google.maps.Geocoder) כדאי להשתמש באפשרות הזו אם כבר יש לכם מחרוזת כתובת מלאה וחד-משמעית ואתם צריכים קואורדינטות במפה.
המרת קואורדינטות GPS או קואורדינטות של מפה שנלחצה ({ lat, lng }) לכתובת רחוב קריאה לאנשים (המרת קואורדינטות לכתובות) geocoder.geocode({ location }) (google.maps.Geocoder) אפשר להשתמש בו לדיווח מהשטח, להצבת סיכות למשלוחים או להצגת כתובת הרחוב הקרובה ביותר לקואורדינטה.
חיפוש כתובת בהשלמה אוטומטית בזמן שהמשתמש מקליד בשדה להזנת קלט <gmp-place-autocomplete> (PlaceAutocompleteElement) משתמשים בשיטה הזו בתיבות חיפוש אינטראקטיביות בזמן שהמשתמש מקליד, במקום להפעיל את Geocoder בכל הקשה על מקש.
אימות כתובת למשלוח או לתשלום, סטנדרטיזציה של רכיבי דואר או בדיקת אפשרות המסירה ליחידות משנה וליחידות Address Validation API (POST https://addressvalidation.googleapis.com/v1:validateAddress) אפשר להשתמש בו בתהליכי תשלום במסחר אלקטרוני, בטופסי משלוח ובתהליכי עבודה שבהם צריך לאשר אם אפשר לשלוח דואר לכתובת או למספר דירה/יחידה (שלא מאומתים על ידי Geocoder).
לפתור קואורדינטה (lat, lng) וחותמת זמן לקיזוז UTC‏ (rawOffset,‏ dstOffset) ו-IANA‏ timeZoneId Time Zone API (GET https://maps.googleapis.com/maps/api/timezone/json) משתמשים בשירות הזה כשצריך את מזהה אזור הזמן של IANA, את הסטייה משעון UTC או את הסטייה של שעון הקיץ עבור קואורדינטה וחותמת זמן (שלא מוחזרות על ידי Geocoder).