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

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

סקירה כללית

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

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

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

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

איך מתחילים

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

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

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

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

תמחור

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

מדיניות

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

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

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

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

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

  • boundsLatLngBounds שבאמצעותו ההטיות של הקוד הגיאוגרפי יבלטו יותר. הפרמטר bounds ישפיע רק על התוצאות מהמקודד, ללא הגבלה. מידע נוסף על תעדוף לפי אזור התצוגה זמין בהמשך.
  • componentRestrictions — משמש להגבלת התוצאות בתחום מסוים. מידע נוסף על סינון רכיבים מופיע בהמשך.
  • region — קוד האזור, שצוין כתג משנה משני של אזור (Unicode) שאינו מספרי. ברוב התגים האלה, המיפוי מתבצע ישירות לדומיין ccTLD ('דומיין ברמה עליונה') עם שני תווים. הפרמטר region ישפיע רק על תוצאות מהמקודד, ללא הגבלה. מידע נוסף על הטיית קוד של אזור מופיע בהמשך.

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

כדי להשתמש בשירות המרת הקידוד הגיאוגרפי, נדרשת שיטת קריאה חוזרת (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 8th Avenue, New York, NY" מכילה את הרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (הנתיב), "New York" (העיר) ו-"NY" (מדינת ארה"ב).

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

  • address_components[] הוא מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.

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

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

    כדאי לשים לב לעובדות הבאות על המערך של address_components[]:

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

    מידע נוסף מפורט במאמר סוגי כתובות וסוגי רכיבים של כתובות.

  • partial_match מציין שהמקודד הגרפי לא החזיר התאמה מדויקת עבור הבקשה המקורית, למרות שהוא הצליח להתאים לחלק מהכתובת המבוקשת. כדאי לבדוק את הבקשה המקורית לשגיאות כתיב ו/או לכתובת חלקית.

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

  • place_idהוא מזהה ייחודי של מקום, וניתן להשתמש בו עם ממשקי API אחרים של Google. לדוגמה, ניתן להשתמש ב-place_id עם ספריית API של מקומות Google כדי לקבל פרטים על עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות של משתמשים ועוד. אפשר לקרוא את הסקירה הכללית של מזהה המקום.
  • 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 מציין את הישות הפוליטית הלאומית, והוא בדרך כלל מסוג הסדר הגבוה ביותר שמחזיר ה-geocoder.
  • administrative_area_level_1 מציין ישות אזרחית בהזמנה ראשונה מתחת לרמת המדינה. רמות הניהול האלה בארה"ב הן מדינות. לא כל האומות מציגות את רמות הניהול האלה. ברוב המקרים, שמות מקוצרים של admin_region_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>

דוגמה.

הטיה באזור התצוגה

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

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

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

במקום לספק 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;
דוגמה

לדגום