הודעת אבטחה: נודע לנו על בעיית אבטחה שעשויה להשפיע על אתרים שמשתמשים בספריות ספציפיות של צד שלישי (כולל polyfill.io). בעיה זו עלולה לפעמים להפנות מבקרים אל מחוץ לאתר המיועד ללא ידיעתו או אישור של בעלי האתר. רבות מדוגמאות ה-JavaScript שלנו כללו בעבר הצהרה של סקריפט polyfill.io. הסרנו את הדוגמאות האלה מהדוגמאות. אם השתמשת בדוגמאות JavaScript שלנו שמכילות את ההצהרה הזו, מומלץ להסיר את ההצהרה.

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

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

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

סקירה כללית

קידוד גיאוגרפי הוא התהליך של המרת כתובות (כמו "30 Herzl Ave, Jerusalem" לקואורדינטות גיאוגרפיות (כמו קו הרוחב 37.423021 וקו האורך -122.083739), שבו אפשר להשתמש כדי סמני מקום או למקם את המפה.

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

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

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

תחילת העבודה

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

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

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

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

תמחור

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

מדיניות

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

street_address מציין כתובת פיזית מדויקת.
route מציין מסלול בעל שם (כגון 'US 101').
intersection מציין צומת ראשי, בדרך כלל שתיים כבישים ראשיים.
political מציין ישות פוליטית. בדרך כלל, הסוג הזה מציין פוליגון של מנהל אזרחי מסוים.
country מציין את הישות הפוליטית הלאומית, והוא בדרך כלל סוג ההזמנה הגבוה ביותר שהוחזר על ידי ה-Geocoder.
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 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" מציין שהקידוד הגיאוגרפי הצליח אבל לא החזיר תוצאות. מצב כזה יכול לקרות אם הועבר באמצעות הקואורדינטות 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 onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </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 שמגדיר תיבה תוחמת (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 עבור 'בריטניה').

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

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

סינון רכיבים

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

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

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

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

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