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