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

דילוג לתוכן הראשי

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

סקירה כללית

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

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

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

ב-Maps JavaScript API יש כיתה של Geocoder להמרת כתובות לקואורדינטות (geocoding) ולהמרת קואורדינטות לכתובות (reverse geocoding) באופן דינמי מהקלט של המשתמש. אם במקום זאת אתם רוצים להמיר כתובות ידועות וסתמיות לקואורדינטות, תוכלו לעיין במאמר שירות האינטרנט להמרת כתובות לקואורדינטות.

שנתחיל?

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

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

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

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

תמחור

למידע על התמחור ועל מדיניות השימוש בשירות המרת כתובות לקואורדינטות (geocoding) ב-JavaScript, קראו את המאמר שימוש וחיוב בנושא Geocoding API.

מדיניות

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

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

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

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

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

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

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

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

תגובות להמרת כתובות לקואורדינטות (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 } }

השדות האלה מוסברים בהמשך:

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

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

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

לכתובות יכולים להיות כמה סוגים. אפשר להתייחס לסוגי הנתונים האלה כ 'תגים'. לדוגמה, ערים רבות מתויגות בסוגי התגים political ו-locality.

יש תמיכה בסוגי הנתונים הבאים, והם מוחזרים גם במערך של סוג הכתובת וגם במערך של סוג רכיב הכתובת:

סוג כתובת תיאור
street_address כתובת רחוב מדויקת.
route מסלול בעל שם (למשל 'כביש 6').
intersection צומת ראשית, בדרך כלל של שני כבישים ראשיים.
political ישות פוליטית. בדרך כלל, הסוג הזה מציין פוליגון של רשות אזרחית כלשהי.
country הישות הפוליטית הלאומית, ובדרך כלל סוג הסדר הגבוה ביותר שמוחזר על ידי המקודד הגיאוגרפי.
administrative_area_level_1 ישות אזרחית ברמה ראשית מתחת לרמת המדינה. בארצות הברית, הרמות האלה הן המדינות. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית. ברוב המקרים, השמות הקצרים של administrative_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 עשוי להחזיר אחד מהערכים הבאים:

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

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); } }); }

להצגת דוגמה

הטיה של אזור התצוגה

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

{ "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:

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

לדוגמה, כתובת גיאוגרפית של 'Toledo' מחזירה את התוצאה הזו, כי הדומיין שמוגדר כברירת מחדל לשירות הגיאוקוד הוא ארצות הברית:

{ "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 ולא כ-OR.

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

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

בדוגמה הבאה מוצגת ההתנהגות הזו עבור קו הרוחב/קו האורך באנטארקטיקה. גם אם אין תוצאות של המרה הפוכה של כתובת לקואורדינטות, עדיין אפשר להדפיס את קוד ה-Plus בהבטחה אם מגדירים את 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 בבקשת גיאוקוד, בבקשת המרת קואורדינטות לכתובות (reverse geocoding) או בבקשת גיאוקוד של מקומות.

דוגמה להמרה של מיקומים לקואורדינטות

השאילתה הבאה מכילה את הכתובת של מקום בדלהי.

function addressDescriptorPlaceIdLookup() { geocoder.geocode({ 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); } }); }

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

השאילתה הבאה מכילה את הערך של קו הרוחב/קו האורך של מיקום בדלהי.

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

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

הכיסוי של תיאור הכתובת

תיאורי הכתובות מופיעים ב-GA בהודו. השימוש בתיאורי כתובות בהודו לא כרוך בעלות נוספת, והשימוש מכוסה על ידי מק"ט Essentials של שירותי גיאוקוד (הודו) הקיים.

משוב

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

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

המונח גיאוקוד מתייחס בדרך כלל לתרגום של כתובת שאנשים יכולים לקרוא למיקום במפה. התהליך ההפוך, שבו ממירים מיקום במפה לכתובת שקריאה לבני אדם, נקרא גיאוקוד הפוך.

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

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

דוגמה לרשימה של הכתובות שתתקבל מהשאילתה שלמעלה:

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.

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

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

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

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

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

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;

להצגת דוגמה

ניסיון של דוגמה

אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers‏.‏ Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.

עדכון אחרון: 2025-06-10 (שעון UTC).