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

דף זה תורגם על ידי Cloud Translation API.

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

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

סקירה

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

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

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

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

איך מתחילים

לפני שמשתמשים בשירות הקידוד הגיאוגרפי ב-Maps JavaScript API, צריך לוודא ש-Geocoding API מופעל במסוף Google Cloud באותו פרויקט שהגדרת ל-Maps JavaScript API.

כדי להציג את רשימת ממשקי ה-API המופעלים:

נכנסים למסוף Google Cloud.
לוחצים על הלחצן Select a project, בוחרים את אותו הפרויקט שהגדרתם ב-Maps JavaScript API ולוחצים על Open.
ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Geocoding API.
אם ה-API מופיע ברשימה, אז לא צריך לבצע פעולה נוספת. אם ה-API לא מופיע ברשימה, מפעילים אותו:
1. בחלק העליון של הדף לוחצים על ENABLE API כדי להציג את הכרטיסייה ספרייה. לחלופין, בתפריט שמשמאל לוחצים על Library.
2. מחפשים את Geocoding API ובוחרים אותו מרשימת התוצאות.
3. בוחרים באפשרות הפעלה. בסיום התהליך יופיע Geocoding API ברשימת ממשקי ה-API במרכז הבקרה.

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

תמחור

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

כללי מדיניות

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

בקשות לקידוד גיאוגרפי

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

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

קידוד גיאוגרפי של התשובות

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

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

תוצאות הקידוד הגיאוגרפי

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

הכתובת המעוצבת מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת 'שדרות רוטשילד 11, תל אביב' מורכבת מהרכיבים הבאים: '111' (המספר ברחוב), 'השדרה השמיני' (המסלול), 'תל אביב' (העיר) ו-'תל אביב' (מדינת ארה"ב).

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

כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:
- types[] הוא מערך שמציין את הסוג של רכיב הכתובת. לרשימת הסוגים הנתמכים
- long_name הוא הטקסט המלא או התיאור של רכיב הכתובת כפי שהוחזר על ידי המקודד הגיאוגרפי.
- short_name הוא שם טקסט מקוצר של רכיב הכתובת, אם יש כזה. לדוגמה, רכיב הכתובת של מדינת אלסקה עשוי להכיל long_name של "Alaska" ו-short_name של "AK" באמצעות קיצור הדואר בן 2 האותיות.
שימו לב לעובדות הבאות לגבי המערך address_components[]:
- מערך רכיבי הכתובת עשוי להכיל יותר רכיבים מאשר formatted_address.
- המערך לא כולל בהכרח את כל הישויות הפוליטיות שמכילות כתובת, מלבד אלה שכלולות ב-formatted_address. כדי לאחזר את כל הישויות הפוליטיות שמכילות כתובת ספציפית, צריך להשתמש בקידוד גיאוגרפי הפוך ולהעביר את קו הרוחב/קו האורך של הכתובת כפרמטר לבקשה.
- לא בטוח שהפורמט של התשובה יהיה זהה בכל הבקשות. באופן ספציפי, מספר הaddress_components משתנה בהתאם לכתובת המבוקשת, והוא עשוי להשתנות עם הזמן עבור אותה כתובת. רכיב יכול לשנות את המיקום במערך. סוג הרכיב יכול להשתנות. יכול להיות שרכיב מסוים יהיה חסר בתשובה מאוחרת יותר.
בהמשך מופיע מידע נוסף על סוגי כתובות וסוגי רכיבי כתובת.
partial_match מציין שהקואורדינטות לא החזירו התאמה מדויקת לבקשה המקורית, למרות שהוא הצליח להתאים חלק מהכתובת המבוקשת. כדאי לבדוק את הבקשה המקורית עם שגיאות כתיב ו/או כתובת חלקית.

לרוב מתרחשות התאמות חלקיות לכתובות רחובות שלא קיימות ברשות המוניציפאלית שאתם מעבירים בבקשה. יכול להיות שהמערכת תחזיר גם התאמות חלקיות כאשר הבקשה תואמת לשני מיקומים או יותר באותו רשות מוניציפאלית. לדוגמה, הטקסט "Hillpar St, Bristol, UK" יחזיר התאמה חלקית גם ל-Henry Street וגם ל-Henrietta Street. שימו לב שאם הבקשה כוללת רכיב כתובת עם שגיאות איות, שירות הקידוד הגיאוגרפי עשוי להציע כתובת חלופית. הצעות שמופעלות באופן הזה יסומנו גם כהתאמה חלקית.
place_id הוא מזהה ייחודי של מקום, ואפשר להשתמש בו בשילוב עם Google APIs אחרים. לדוגמה, אפשר להשתמש ב-place_id עם הספרייה Google Places API כדי לקבל פרטים על עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות של משתמשים ועוד. ראו סקירה כללית על מזהה המקום.
postcode_localities[] הוא מערך שמציין את כל הרשות המוניציפאלית שכלולה במיקוד, והוא מופיע רק כשהתוצאה היא מיקוד שמכיל כמה יישובים.
geometry מכיל את המידע הבא:
- location מכיל את הערך של קו האורך וקו הרוחב המקודד גיאוגרפי. שימו לב שאנחנו מחזירים את המיקום הזה כאובייקט LatLng, ולא כמחרוזת בפורמט.
- נתונים נוספים לגבי המיקום שצוין נשמרים ב-location_type. הערכים הבאים נתמכים כרגע:
  - ROOFTOP מציין שהתוצאה שהוחזרה משקפת קוד גיאוגרפי מדויק.
  - RANGE_INTERPOLATED מציין שהתוצאה שמוחזרת משקפת הערכה (בדרך כלל בכביש) ששונה בין שתי נקודות מדויקות (כמו צמתים). בדרך כלל מוחזרות תוצאות עם אינטרפולציה אם אין כתובת פיזית זמינה על הגגות.
  - GEOMETRIC_CENTER מציין שהתוצאה שהוחזרה היא המרכז הגאומטרי של תוצאה, כמו קו פוליגוני (לדוגמה, רחוב) או פוליגון (אזור).
  - APPROXIMATE מציין שהתוצאה שהוחזרה היא משוערת.
- viewport שומר את אזור התצוגה המומלץ של התוצאה שהוחזרה.
- השדה bounds (אפשר להחזיר אותו) מאחסן את LatLngBounds, שיכול להכיל באופן מלא את התוצאה שהוחזרה. שימו לב: ייתכן שהגבולות האלה לא יתאימו לאזור התצוגה המומלץ. (לדוגמה, סן פרנסיסקו כוללת את איי פארלון, שטכנית הם חלק מהעיר, אבל אין להחזיר אותם באזור התצוגה).

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

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

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

הקואורדינטות הבאות נתמכות ומוחזרות על ידי הקואורדינטות, גם בסוגי הכתובות וגם בסוגי רכיבי הכתובת:

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

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

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body >
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" >
  </div>
</body>

להצגת דוגמה.

הטיה באזור התצוגה

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

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

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

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

כשמשתמשים בפרמטר 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"
}

הקוד הגיאוגרפי של 'טולדו' עם השדה region מוגדר כ-'es' (ספרד) יחזיר את העיר הספרדית:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

סינון רכיבים

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

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

מסנן רכיבים מורכב מאחד או יותר מהפריטים הבאים:

route תואם לשם ארוך או קצר של מסלול.
locality התאמות לסוגים של רשויות מוניציפאליות ומחוזות משנה.
administrativeArea תואם לכל הרמות של האזור המנהלי.
postalCode תואם למיקודים ולקידומות של מיקוד.
הערך country תואם לשם מדינה או לקוד מדינה של ISO 3166-1 בן שתי אותיות. הערה: ה-API תואם לתקן ISO להגדרת מדינות, והסינון פועל בצורה הטובה ביותר כשמשתמשים בקוד ה-ISO התואם של המדינה.

הדוגמה הבאה ממחישה את השימוש בפרמטר componentRestrictions כדי לסנן לפי country ו-postalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

מילוי הזמנות באפס תוצאות

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

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

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

מתארי כתובת

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

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

דוגמה בקידוד גיאוגרפי של מקומות

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

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

דוגמה בקידוד גיאוגרפי הפוך

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

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

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

כך נראה address_descriptor לדוגמה.

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

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

place_id הוא מזהה המקום של התוצאה של ציוני הדרך. ראו סקירה כללית על מזהה המקום.
display_name הוא השם המוצג של ציון הדרך, והוא מכיל את language_code ואת text.
straight_line_distance_meters הוא המרחק של הנקודה במטרים בין קואורדינטת הקלט לתוצאה של ציוני הדרך.
travel_distance_meters הוא המרחק במטרים שנסעו דרך רשת הכבישים (תוך התעלמות ממגבלות הכבישים) בין קואורדינטה הקלט לתוצאה של ציוני הדרך.
spatial_relationship הוא הקשר המשוער בין קואורדינטת הקלט לתוצאה של ציוני הדרך:

"NEAR" הוא קשר ברירת המחדל כאשר אף אחד מהתנאים הבאים לא רלוונטי.
"WITHIN" כאשר קואורדינטת הקלט נמצאת בתוך גבולות המבנה שמשויך לציון הדרך.
"BESIDE" כשקואורדינטת הקלט סמוך ישירות לנקודת הגישה של ציון הדרך או ציון הדרך.
"ACROSS_THE_ROAD" כאשר קואורדינטת הקלט נמצאת ישירות מול ציון הדרך בצד השני של המסלול.
"DOWN_THE_ROAD" כאשר קואורדינטת הקלט נמצאת באותו מסלול כמו ציון הדרך, אבל לא "BESIDES" או "ACROSS_THE_ROAD".
"AROUND_THE_CORNER" כשקואורדינטת הקלט נמצאת במסלול מאונך כציון הדרך (מוגבל לפנייה אחת).
"BEHIND" כאשר קואורדינטת הקלט קרובה מבחינה מרחבית לציון הדרך, אבל רחוקה מנקודת הגישה שלה.

types הם סוגי המקומות של ציון הדרך.

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

place_id הוא מזהה המקום של תוצאת האזורים. ראו סקירה כללית על מזהה המקום.
display_name הוא השם המוצג של האזור, והוא מכיל את language_code ואת text.
containment הוא קשר הגבולות המשוער בין קואורדינטת הקלט לתוצאת האזורים:

"NEAR" הוא קשר ברירת המחדל כאשר אף אחד מהתנאים הבאים לא רלוונטי.
"WITHIN" כשקואורדינטת הקלט קרובה למרכז האזור.
"OUTSKIRTS" כשקואורדינטת הקלט קרובה לקצה האזור.

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

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

זוהי תכונה של תצוגה מקדימה ונשמח לקבל משוב. אפשר לשלוח לנו אימייל לכתובת address-descriptors-feedback@google.com.

הפיכת הקידוד הגיאוגרפי (חיפוש כתובת)

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

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

הערה: אם כוללים את הפרמטר componentRestrictions בבקשה, המערכת מתעלמת מהפרמטר location.

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

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

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

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;index.js

להצגת דוגמה

כדאי לנסות דוגמה

JSFiddle.net Google Cloud Shell

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

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

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

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

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

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

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

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

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

address
latLng
location
componentRestrictions

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