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

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

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

סקירה כללית

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

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

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

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

איך מתחילים

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

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

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

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

תמחור

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

כללי מדיניות

השימוש בשירות Geocoding חייב לציית למדיניות המתוארת עבור Geocoding API.

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

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

ניתן לגשת לשירות המרת הקואורדינטות (geocoding) של מפות Google בקוד שלך באמצעות אובייקט הבנייה google.maps.Geocoder. השיטה 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 ישפיע רק על תוצאות המקודדות, אבל לא באופן מלא. למידע נוסף על הטיה של קוד אזור בהמשך.

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

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

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

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

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

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

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

ברוב המקרים, התאמות חלקיות מתרחשות לגבי כתובות שאינן קיימות באזור המגורים שאתם מעבירים בבקשה. אנחנו עשויים להחזיר התאמות חלקיות גם כשבקשה תואמת לשני מיקומים או יותר באותו אזור. לדוגמה, "Hilpar St, בריסטול, בריטניה" תחזיר התאמה חלקית גם לרחוב הנרי ולרחוב הנרייטה. שימו לב שאם בקשה כוללת רכיב כתובת עם שגיאות כתיב, יכול להיות ששירות הקידוד הגיאוגרפי יציע כתובת חלופית. גם הצעות שמופעלות כך יסומנו כהתאמה חלקית.
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[] גם יוחזר בתוך GecoderAddressComponent כדי לציין את הסוג של רכיב הכתובת הספציפי. כתובות שמוחזרות על ידי המקודד עשויות להכיל סוגים מרובים. הסוגים עשויים להיחשב כתגים. לדוגמה, ערים רבות מתויגות באמצעות סוג ה-political ו-locality.

ה-מקודד יתמוך בסוגים הבאים של כתובות וסוגים של כתובות, ויחזיר אותם:

הכתובת street_address מציינת כתובת מדויקת.
route מציין נתיב בעל שם (כגון "101 US").
intersection מציין צומת ראשי, בדרך כלל של {0/} כבישים ראשיים.
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 מציין נקודת ציון בעלת שם. בדרך כלל, "נקודות העניין" האלה הן ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו "בניין האמפייר סטייט" או "מגדל אייפל".

רשימת סוגים ריקה מציינת שאין סוגים ידועים של רכיב הכתובת הספציפי, לדוגמה, Liu-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"
}

הטיה לפי קוד אזור

אפשר להגדיר את השירות Geocoding כדי להחזיר תוצאות משופעות לאזור מסוים באמצעות הפרמטר region. הפרמטר הזה מקבל קוד אזור, שמצוין כתג משנה של אזור Unicode דו-תווים (לא מספרי). התגים האלה ממופים ישירות אל ccTLD (דומיין ברמה העליונה) מוכר של שני תווים, כמו 'uk' ב-'co.uk' לדוגמה. במקרים מסוימים, התג region תומך גם בקודי ISO-3166-1, שפעמים שונים מערכי ccTLD (לדוגמה: "GB" ל "בריטניה").

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

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

סינון רכיבים

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

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

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

TypeScript

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

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

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

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

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

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

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

JavaScript

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

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

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

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

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

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

window.initMap = initMap;index.js

דוגמה

לדגימה

JSFiddle.net CodeSandbox.io Google Cloud Shell

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

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

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

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

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

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

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

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

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

address
latLng
location
componentRestrictions

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