סקירה כללית
קידוד גיאוגרפי הוא התהליך של המרת כתובות (כמו "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 לא מופיע ברשימה,
להפעיל אותו:
- בחלק העליון של הדף, בוחרים באפשרות ENABLE API כדי להציג את ספרייה. לחלופין, בתפריט שבצד שמאל, בוחרים באפשרות ספרייה.
- מחפשים את Geocoding API ובוחרים אותו מתוך רשימת התוצאות.
- בוחרים באפשרות הפעלה. כשהתהליך מסתיים, 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
, בסדר הזה.
תוצאות הקידוד הגיאוגרפי
האובייקט 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"
כשקואורדינטת הקלט קרובה לקצה האזור.
כיסוי של מתאר הכתובת
התכונה הזו זמינה רק באזורים נבחרים מדינות.
זוהי תכונה של תצוגה מקדימה ונשמח לקבל משוב. צריך לשלוח אימייל אלינו בכתובת [email protected].
הפיכת הקידוד הגיאוגרפי (חיפוש כתובת)
המושג קידוד גיאוגרפי מתייחס בדרך כלל לתרגום של טקסט קריא לאנשים את הכתובת למיקום במפה. התהליך של ביצוע ההפך, תרגום של מיקום במפה לכתובת שבודק אנושי יכול לקרוא המרת קידוד גיאוגרפי.
במקום לספק address
טקסט, צריך לספק קובץ מופרד בפסיקים
צמד של קו רוחב/קו אורך בפרמטר 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;
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;
כדאי לנסות דוגמה
שימו לב שבדוגמה הקודמת הצגנו את התוצאה הראשונה לפי
בחרת באפשרות 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
בדוגמה הבאה מקבלים מזהה מקום, ומוצאים את הכתובת המתאימה, וממרכז את המפה במיקום הזה. נוצר גם חלון מידע הכתובת בפורמט של המקום הרלוונטי:
TypeScript
// Initialize the map. function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 8, center: { lat: 40.72, lng: -73.96 }, } ); const geocoder = new google.maps.Geocoder(); const infowindow = new google.maps.InfoWindow(); (document.getElementById("submit") as HTMLElement).addEventListener( "click", () => { geocodePlaceId(geocoder, map, infowindow); } ); } // This function is called when the user clicks the UI button requesting // a geocode of a place ID. function geocodePlaceId( geocoder: google.maps.Geocoder, map: google.maps.Map, infowindow: google.maps.InfoWindow ) { const placeId = (document.getElementById("place-id") as HTMLInputElement) .value; geocoder .geocode({ placeId: placeId }) .then(({ results }) => { if (results[0]) { map.setZoom(11); map.setCenter(results[0].geometry.location); const marker = new google.maps.Marker({ map, position: results[0].geometry.location, }); infowindow.setContent(results[0].formatted_address); infowindow.open(map, marker); } else { window.alert("No results found"); } }) .catch((e) => window.alert("Geocoder failed due to: " + e)); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// Initialize the map. function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 8, center: { lat: 40.72, lng: -73.96 }, }); const geocoder = new google.maps.Geocoder(); const infowindow = new google.maps.InfoWindow(); document.getElementById("submit").addEventListener("click", () => { geocodePlaceId(geocoder, map, infowindow); }); } // This function is called when the user clicks the UI button requesting // a geocode of a place ID. function geocodePlaceId(geocoder, map, infowindow) { const placeId = document.getElementById("place-id").value; geocoder .geocode({ placeId: placeId }) .then(({ results }) => { if (results[0]) { map.setZoom(11); map.setCenter(results[0].geometry.location); const marker = new google.maps.Marker({ map, position: results[0].geometry.location, }); infowindow.setContent(results[0].formatted_address); infowindow.open(map, marker); } else { window.alert("No results found"); } }) .catch((e) => window.alert("Geocoder failed due to: " + e)); } window.initMap = initMap;