מדריך מקוצר ל-Geocoding API

‫Geocoding API הוא שירות אינטרנט שממיר כתובות לקואורדינטות ולמזהי מקומות, וממיר קואורדינטות או מזהי מקומות לכתובות. השיטה v4 SearchDestinations מחזירה גם פרטים על היעד, כמו כניסות לבניינים, נקודות ניווט, קווי מתאר של מבנים ושטחים וציוני דרך בקרבת מקום.

‫Geocoding API: עובדות חשובות

  • מוצר: Geocoding API
  • קטגוריה: מקומות
  • פלטפורמה: שירות אינטרנט (REST)
  • פועל ב: שרת (קוד לקצה העורפי)
  • שלב ההשקה: GA
  • מחזור חיים: פעיל
  • סקירה כללית: סקירה כללית על Geocoding API

מתי כדאי להשתמש ב-Geocoding API

מתי כדאי להשתמש ב-Geocoding API:

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

מתי לא כדאי להשתמש ב-Geocoding API:

  • אתם צריכים לבצע המרת כתובות לקואורדינטות מ-JavaScript בדפדפן בצד הלקוח. קריאה לגרסה 4 עם מפתח API חשוף היא סיכון אבטחה. במקום זאת, צריך להשתמש ב-Maps JavaScript API.
  • אתם צריכים לחשב מסלול או זמן הגעה משוער ליעד שהכתובת שלו הומרה לקואורדינטות. במקום זאת, אתם צריכים להשתמש ב-Routes API.
  • אתם צריכים מסלול מפורט לטוקן של נקודת ניווט באפליקציה ל-Android. במקום זאת, השתמשו ב-Navigation SDK ל-Android.
  • אתם צריכים הנחיות מסלול מפורט לטוקן של נקודת ניווט באפליקציה ל-iOS. במקום זאת, השתמשו ב-Navigation SDK ל-iOS.

‫Geocoding API: הגדרה

‫Geocoding API: טעויות נפוצות

  • הבעיה: בקשות SearchDestinations ללא אנונימיזציה של שדות נכשלות עם שגיאה. בניגוד ל-GeocodeAddress, ל-GeocodeLocation ול-GeocodePlace, אנונימיזציה של שדות היא חובה. תיקון: מגדירים את הכותרת X-Goog-FieldMask או את הפרמטר $fields בכל בקשת SearchDestinations. מידע נוסף זמין בכתובת /maps/documentation/geocoding/choose-fields.
  • הבעיה: בגרסה 4 של GeocodeAddress אין מסנן רכיבים קשיח (בגרסה 3 של components=country:US). פרמטרים מובְנים של address.* משולבים בכתובת אחת ולא מסננים את התוצאות. בנוסף, ל-regionCode אין ברירת מחדל בגרסה 4 (בגרסה 3 ברירת המחדל הייתה us). הפתרון: מסננים את results בצד הלקוח: מתאימים את regionCode באותיות רישיות ל-postalAddress.regionCode, מתאימים אזורים מנהליים באותיות רישיות עם 2 אותיות ל-postalAddress.administrativeArea ול-administrative_area_level_n addressComponents (shortText), מנרמלים גם את הקלט וגם את postalAddress.postalCode (מסירים רווחים/מקפים ומחילים כללי אזור). מידע נוסף זמין בכתובת /maps/documentation/geocoding/geocoding-v4-migrate.
  • הבעיה: קריאה ל-Geocoding API v4 ישירות מ-JavaScript בדפדפן חושפת את מפתח ה-API. אפשר לעקוף את ההגבלות על גורמים מפנים מסוג HTTP על ידי זיוף הכותרת Referer. תיקון: שולחים קריאה לגרסה 4 מה-backend שלכם עם מפתח מוגן, או משתמשים בשירות המרת הכתובות לקואורדינטות (geocoding) של Maps JavaScript API (‏backend בגרסה 3) לצרכים בצד הלקוח. /maps/documentation/geocoding/geocoding-v4-migrate
  • הבעיה: בניגוד לגרסה 3 ולשיטות האחרות של גרסה 4, יכול להיות שהשיטה SearchDestinations תחזיר תוצאות שאין להן כתובת ראשית מדויקת. תיקון: מגדירים את placeFilter.addressability כ-PRIMARY כשצריך רק תוצאות עם כתובות ראשיות מדויקות. מידע נוסף זמין בכתובת /maps/documentation/geocoding/geocoding-v4-migrate.
  • הבעיה: קוד שנכתב ל-Geocoding API בגרסה 3 לא פועל בתגובות REST בגרסה 4: בגרסה 4 נעשה שימוש בשמות שדות בפורמט lowerCamelCase (addressComponents, לא address_components), הוסרו status ו-error_message, ומוחזר אובייקט בסיס יחיד מ-GeocodePlace במקום מערך results. תיקון: בודקים את קודי הסטטוס של HTTP ואת גופי השגיאות בקריאות REST בגרסה 4, קוראים את השדות בפורמט lowerCamelCase‏ (addressComponents, postalAddress) וזוכרים שהתגובות של gRPC עדיין משתמשות ב-קו תחתון בין המילים. /maps/documentation/geocoding/geocoding-v4-migrate

‫Geocoding API: תכונות קודמות ותכונות שהוצאו משימוש

  • ‫נתונים לקהילה ממוקדת של Geocoding API v3 (extra_computations: BUILDING_AND_ENTRANCES, NAVIGATION_POINTS, GROUNDS; שדות תגובה buildings.entrances, navigation_points, buildings.building_outlines, grounds): הוצאה משימוש החל מ-13 באוגוסט 2025. החלפה: השיטה SearchDestinations (POST /v4/geocode/destinations) ב-Geocoding API גרסה 4. מידע נוסף זמין במדריך להעברת נתונים (מיגרציה).

מה אפשר לעשות עם Geocoding API

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