סקירה כללית
קידוד גיאוגרפי הוא התהליך של המרת כתובות (כמו " 1600 Amphitheatre Parkway, Mountain View, CA") לקואורדינטות גיאוגרפיות (כמו קו רוחב 37.423021 וקו אורך -122.083739), ולהשתמש בהן כדי להציב סמנים או למקם את המפה.
קידוד גיאוגרפי הפוך הוא התהליך של המרת קואורדינטות גיאוגרפיות לכתובת שאנשים יכולים לקרוא (מידע נוסף זמין בקטע קידוד גיאוגרפי הפוך (חיפוש כתובת)).
אפשר גם להשתמש במקודד הגיאוגרפי כדי למצוא את הכתובת של מזהה מקום נתון.
ה-API של JavaScript במפות Google מספק סיווג גיאוגרפי (Geocoder) של קידוד גיאוגרפי וקידוד גיאוגרפי הפוך באופן דינמי מקלט של משתמשים. אם במקום זאת רוצים להגדיר קידוד גיאוגרפי של כתובות סטטיות וידועות, תוכלו להשתמש בשירות האינטרנט של המרת כתובות לקואורדינטות (geocoding).
תחילת העבודה
לפני השימוש בשירות המרת כתובות לקואורדינטות (geocoding) ב-API של JavaScript למפות Google, צריך קודם לוודא שה-Geocoding API מופעל במסוף Google Cloud באותו הפרויקט שהגדרתם ל- Maps JavaScript API.
כדי לראות את רשימת ממשקי ה-API שמופעלים:
- נכנסים למסוף Google Cloud.
- לוחצים על הלחצן Select a project (בחירת פרויקט), בוחרים את הפרויקט שהגדרתם עבור Maps JavaScript API ולוחצים על Open.
- מחפשים את Geocoding API ברשימת ממשקי ה-API במרכז הבקרה.
- אם ה-API מופיע ברשימה, אז הכול מוכן. אם ממשק ה-API לא מופיע ברשימה,
מפעילים אותו:
- בחלק העליון של הדף, לוחצים על ENABLE API כדי להציג את הכרטיסייה Library. לחלופין, בתפריט מימין לוחצים על ספרייה.
- צריך לחפש את Geocoding API ולבחור אותו מרשימת התוצאות.
- בוחרים באפשרות הפעלה. בסיום התהליך, יופיע Geocoding API ברשימת ממשקי ה-API במרכז השליטה.
תמחור ומדיניות
תמחור
ב-16 ביולי 2018 נכנסה לתוקף תוכנית התמחור החדשה 'תשלום לפי שימוש' עבור מפות Google, מסלולים ומקומות. למידע נוסף על מגבלות התמחור והשימוש החדשות בשירות הקידוד הגיאוגרפי של JavaScript, קראו את המאמר שימוש וחיוב ב-Geocoding API.
כללי מדיניות
השימוש בשירות הקידוד הגיאוגרפי חייב להיות בהתאם למדיניות שמתוארת ב-Geocoding API.
בקשות לקידוד גיאוגרפי
הגישה לשירות הקידוד הגיאוגרפי היא אסינכרונית, כי ה-API של מפות Google צריך לבצע קריאה לשרת חיצוני. לכן, צריך להגדיר שיטת callback כדי להפעיל את התכונה אחרי שתשלימו את הבקשה. שיטת הקריאה החוזרת הזו מעבדת את התוצאות. חשוב לשים לב שהמקודד הגיאוגרפי עשוי להחזיר יותר מתוצאה אחת.
הגישה לשירות הקידוד הגיאוגרפי של ה-API של מפות Google בתוך הקוד מתבצעת דרך
אובייקט הבנאי google.maps.Geocoder
. השיטה
Geocoder.geocode()
שולחת בקשה לשירות הקידוד הגיאוגרפי, ומעבירה לו אובייקט GeocoderRequest
שמכיל את תנאי הקלט ושיטת קריאה חוזרת להפעלה עם קבלת התשובה.
ליטרל של האובייקט 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
ישפיע רק על התוצאות מהמקודד הגיאוגרפי, ולא יגביל אותו באופן מלא. מידע נוסף על הטיה לפי קוד אזור מופיע בהמשך.
תגובות בנושא המרת כתובות לקואורדינטות (geocoding)
לשירות הקידוד הגיאוגרפי יש צורך בשיטת קריאה חוזרת (callback) כדי להפעיל את תהליך אחזור התוצאות של כלי הקידוד הגיאוגרפי. הקריאה החוזרת (callback) צריכה להעביר שני פרמטרים כדי להחזיק את הקוד results
והקוד status
, בסדר הזה.
תוצאות המרת כתובות לקואורדינטות (geocoding)
האובייקט GeocoderResult
מייצג תוצאה אחת
של קידוד גיאוגרפי. בקשה להמרת קוד גיאוגרפי עשויה להחזיר מספר אובייקטי תוצאה:
results[]: { types[]: string, formatted_address: string, address_components[]: { short_name: string, long_name: string, postcode_localities[]: string, types[]: string }, partial_match: boolean, place_id: string, postcode_localities[]: string, geometry: { location: LatLng, location_type: GeocoderLocationType viewport: LatLngBounds, bounds: LatLngBounds } }
השדות האלו מוסברים בהמשך:
types[]
הוא מערך שמציין את סוג הכתובת של התוצאה שהוחזרה. המערך הזה מכיל קבוצה של אפס תגים או יותר שמזהים את סוג התכונה שהוחזרה בתוצאה. לדוגמה, קוד גיאוגרפי של "שיקגו" מחזיר "locality" שמציין ש "שיקגו" היא עיר, וגם מחזיר "פוליטי" שמציין שמדובר בישות פוליטית. בהמשך מופיע מידע נוסף על סוגי כתובות וסוגי רכיבי כתובת.formatted_address
היא מחרוזת שמכילה את הכתובת של המיקום הזה, בפורמט שקריא לבני אדם.לעיתים קרובות, כתובת זו זהה לכתובת למשלוח דואר. לתשומת ליבך: בחלק מהמדינות, כמו בריטניה, אסור להפיץ כתובות למשלוח דואר אמיתיות בגלל הגבלות רישוי.
הכתובת בפורמט הנכון מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת " 111 8th Avenue, New York, NY" מורכבת מהרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (המסלול), "New York" (העיר) ו-"NY" (מדינת ארה"ב).
אל תנתחו את הכתובת בפורמט פרוגרמטי. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכוללים את תגובת ה-API בנוסף לשדה הכתובת המעוצב.
address_components[]
הוא מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:
types[]
הוא מערך שמציין את ה-type של רכיב הכתובת. אפשר לעיין ברשימת הסוגים הנתמכים.long_name
הוא תיאור הטקסט המלא או השם של רכיב הכתובת כפי שמוחזר על ידי ה-Geocoder.short_name
הוא שם טקסט מקוצר של רכיב הכתובת, אם זמין. לדוגמה, רכיב כתובת של מדינת אלסקה יכול לכלול אתlong_name
"אלסקה" ו-short_name
את "AK", באמצעות קיצור בן 2 אותיות.
שימו לב לעובדות הבאות לגבי המערך
address_components[]
:- מערך רכיבי הכתובת עשוי להכיל יותר רכיבים מאשר ה-
formatted_address
. - המערך לא כולל בהכרח את כל הישויות הפוליטיות
שמכילות כתובת, פרט לאלה שכלולות
ב-
formatted_address
. כדי לאחזר את כל הישויות הפוליטיות שמכילות כתובת מסוימת, צריך להשתמש בקידוד גיאוגרפי הפוך, ולציין בבקשה את קו הרוחב/קו האורך של הכתובת כפרמטר. - לא בטוח שהפורמט של התשובה יישאר זהה בין
הבקשות. באופן ספציפי, מספר
address_components
משתנה בהתאם לכתובת המבוקשת, והוא עשוי להשתנות עם הזמן לגבי אותה כתובת. מיקום של רכיב יכול לשנות את מיקומו במערך. סוג הרכיב יכול להשתנות. ייתכן שחסר רכיב מסוים בתגובה מאוחרת יותר.
בהמשך מופיע מידע נוסף על סוגי כתובות וסוגי רכיבי כתובת.
-
partial_match
מציין שהמקודד הגיאוגרפי לא החזיר התאמה מדויקת לבקשה המקורית, למרות שהוא הצליח להתאים לחלק מהכתובת המבוקשת. מומלץ לבדוק את הבקשה המקורית לאיתור שגיאות כתיב ו/או כתובת חלקית.ברוב המקרים, התאמות חלקיות מתרחשות לרחובות שלא קיימים ברשות המוניציפאלית שציינתם בבקשה. התאמות חלקיות עשויות גם לחזור כשבקשה תואמת לשני מיקומים או יותר באותו רשות מוניציפאלית. לדוגמה, "Hillpar St, Bristol, UK" יחזיר התאמה חלקית גם ל-Henry Street וגם ל-Henrietta Street. שימו לב שאם בקשה כוללת רכיב כתובת עם שגיאות איות, שירות הקידוד הגיאוגרפי עשוי להציע כתובת חלופית. הצעות שיופעלו באופן הזה יסומנו גם כהתאמה חלקית.
place_id
הוא מזהה ייחודי של מקום, שאפשר להשתמש בו עם ממשקי API אחרים של Google. לדוגמה, ניתן להשתמש ב-place_id
עם הספרייה של Google Places API כדי לקבל פרטים על עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות של משתמשים ועוד. מידע נוסף זמין בסקירה הכללית על מזהה מקום.postcode_localities[]
הוא מערך שמציין את כל הרשויות המוניציפאליות שכלולות במיקוד. הוא מופיע רק כשהתוצאה היא מיקוד שמכיל מספר רשויות מקומיות.geometry
מכיל את המידע הבא:location
מכיל את ערך קו האורך וקו הרוחב המקודד גיאוגרפית. חשוב לשים לב שאנחנו מחזירים את המיקום הזה כאובייקטLatLng
, ולא כמחרוזת בפורמט.- ב-
location_type
נשמרים נתונים נוספים לגבי המיקום שצוין. כרגע יש תמיכה בערכים הבאים:ROOFTOP
מציין שהתוצאה שהוחזרה משקפת קידוד גיאוגרפי מדויק.RANGE_INTERPOLATED
מציין שהתוצאה שהוחזרה משקפת קירוב (בדרך כלל בכביש) שהושתתה בין שתי נקודות מדויקות (כמו צמתים). בדרך כלל, תוצאות אינטרפולציה מוחזרות כאשר קידוד גיאוגרפי של גגות אינו זמין לכתובת רחוב.GEOMETRIC_CENTER
מציין שהתוצאה שמוחזרת היא המרכז הגאומטרי של תוצאה, כמו קו פוליגוני (לדוגמה, רחוב) או פוליגון (אזור).APPROXIMATE
מציין שהתוצאה שהוחזרה היא משוערת.
- השדה
viewport
שומר את אזור התצוגה המומלץ לתוצאה שהוחזרה. - ב-
bounds
(ניתן החזרה אופציונלית) מאוחסניםLatLngBounds
, שיכול להכיל את התוצאה שהוחזרה במלואה. לתשומת ליבכם: ייתכן שהגבולות האלה לא יתאימו לאזור התצוגה המומלץ. (לדוגמה, סן פרנסיסקו כוללת את איי פארלון, שטכנית הם חלק מהעיר, אבל אסור להחזיר אותם באזור התצוגה).
ה-Geocoder יחזיר את הכתובות לפי הגדרת השפה
המועדפת של הדפדפן, או השפה שצוינה בזמן טעינת ה-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 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
שמגדיר תיבה תוחמת את עמק סן פרננדו בלוס אנג'לס יגרום לכך שהקידוד הגיאוגרפי הזה יחזיר את השכונה בשם "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 מציעה קידוד גיאוגרפי. שימו לב שההטיה מעדיפה רק לתוצאות מדומיין מסוים. אם קיימות תוצאות רלוונטיות יותר מחוץ לדומיין הזה, ייתכן שהן ייכללו.
לדוגמה, קוד גיאוגרפי של "טולדו" מחזיר את התוצאה הזו, כדומיין ברירת המחדל עבור שירות הקידוד הגיאוגרפי מוגדר לארצות הברית:
{ "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); } }); }
קידוד גיאוגרפי הפוך (חיפוש כתובת)
המונח קידוד גיאוגרפי מתייחס בדרך כלל לתרגום של כתובת שאנשים יכולים לקרוא למיקום במפה. התהליך ההפוך, תרגום של מיקום במפה לכתובת שאנשים יכולים לקרוא, נקרא קידוד גיאוגרפי הפוך.
במקום לציין 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;