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

הערה: ספריות בצד השרת

בדף הזה מתואר השירות בצד הלקוח שזמין באמצעות Maps JavaScript API. אם אתם רוצים לעבוד עם שירותי האינטרנט של מפות Google בשרת שלכם, כדאי לעיין בלקוח Node.js לשירותי מפות Google. בדף הזה יש גם הסבר על לקוח Java, לקוח Python ולקוח Go לשירותי מפות Google.

מפתחים באזור הכלכלי האירופי (EEA)

אם כתובת החיוב שלכם נמצאת באזור הכלכלי האירופי, החל מ-8 ביולי 2025, התנאים וההגבלות של Google Maps Platform למשתמשים באזור הכלכלי האירופי יחולו על השימוש שלכם בשירותים. הפונקציונליות יכולה להיות שונה בין אזור לאזור. מידע נוסף

סקירה כללית

אפשר גם לעיין בהפניה ל-Maps JavaScript API:‏ Geocoder

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

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

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

‫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 בלוח הבקרה.

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

תמחור

מידע על התמחור ומדיניות השימוש בשירות המרת כתובות לקואורדינטות (geocoding) ב-JavaScript זמין במאמר בנושא שימוש וחיוב ב-Geocoding API.

מדיניות

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

Geocoding Requests

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

רה

אתם ניגשים לשירות הגיאוקודינג של Google Maps API בתוך הקוד באמצעות אובייקט ה-constructor‏ google.maps.Geocoder. ה-method‏ 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 — קוד האזור, שמוגדר כערך ccTLD (דומיין ברמה העליונה) באורך שני תווים. ברוב המקרים, התגים האלה ממופים ישירות לערכים מוכרים של ccTLD (דומיין ברמה העליונה) באורך שני תווים. הפרמטר region ישפיע על התוצאות מהגיאוקודר, אבל לא יגביל אותן באופן מלא. בהמשך מופיע מידע נוסף על הטיה של קוד האזור.
• ‫extraComputations – הערך המותר היחיד לפרמטר הזה הוא ADDRESS_DESCRIPTORS. פרטים נוספים מופיעים במאמר בנושא מתארי כתובות.
• ‫fulfillOnZeroResults — צריך למלא את ההבטחה בסטטוס ZERO_RESULT בתגובה. יכול להיות שתרצו לעשות את זה כי גם אם לא מתקבלות תוצאות של קידוד גיאוגרפי, יכול להיות שעדיין יוחזרו שדות נוספים ברמת התגובה. פרטים נוספים מופיעים במאמר בנושא השלמת הזמנה כשאין תוצאות.

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

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

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

תוצאות של המרת כתובות לקואורדינטות (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 Alaska ואת הערך 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	נקודת עניין עם שם. בדרך כלל, נקודות העניין האלה הן ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו "Empire State Building" או "Eiffel Tower".

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

הערה: כדאי לקרוא את המדריך בנושא שימוש ב-TypeScript ובמפות Google.

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)
        );
    }
}
index.js

דוגמה מלאה

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

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

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

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

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

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

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

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

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

השלמת פעולה כשאין תוצאות

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

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

הערה: לא כל המקומות תואמים לתיאורי כתובות. למקומות גדולים מאוד (לדוגמה, שדה תעופה) או לאזורים (לדוגמה, אזור מיקוד) אף פעם לא יתווסף תיאור כתובת.

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

הערה: המרת קואורדינטות לכתובות (reverse geocoding) כוללת תיאור כתובת יחידה ברמת התגובה. המרת כתובות לקואורדינטות (geocoding) והמרת מקומות לקואורדינטות (places geocoding) יקבלו תיאור כתובת לכל תוצאה תואמת בתגובה

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

דוגמה ל-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 בכל שאר האזורים. נשמח לקבל משוב:

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

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

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

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

הערה: אם כוללים את הפרמטר componentRestrictions בבקשה, המערכת מתעלמת מהפרמטר 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();
index.ts

הערה: כדאי לקרוא את המדריך לשימוש ב-TypeScript ובמפות Google.

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();
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>
        <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>
index.html

לדוגמה

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

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

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

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

הכתובות מוחזרות בסדר יורד של התאמה. בדרך כלל, הכתובת המדויקת יותר היא התוצאה הבולטת ביותר, כמו במקרה הזה. שימו לב שאנחנו מחזירים סוגים שונים של כתובות, החל מכתובת רחוב ספציפית ביותר ועד לישויות פוליטיות פחות ספציפיות כמו שכונות, ערים, מחוזות, מדינות וכו'. אם אתם רוצים להתאים כתובת כללית יותר, כדאי לבדוק את השדה results[].types.

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

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

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

הערה: כדאי לקרוא את המדריך לשימוש ב-TypeScript ובמפות Google.

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();
index.js

לדוגמה