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-backend.googleapis.com - אימות: מפתח API, OAuth 2.0, חשבון שירות
- איך מתחילים: הגדרת Geocoding API
- חומר עזר: חומר עזר בנושא Geocoding API
- תמחור: שימוש וחיוב ב-Geocoding API
- כללי מדיניות: כללי המדיניות של Geocoding API
- נתוני גרסה: נתוני הגרסה של Geocoding API
Geocoding API: מוצרים קשורים
- ממשקים שמשתמשים בהם לעיתים קרובות עם ה-API הזה: Routes API, Navigation SDK ל-Android, Navigation SDK ל-iOS
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_naddressComponents(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
במדריכים שמקושרים בהמשך מפורטות כל המשימות, ואפשר גם להשוות בין המוצרים בסייר היכולות.
- החזרת הקואורדינטות של קווי האורך והרוחב של כתובת (המרת כתובות לקואורדינטות).
- החזרת הכתובת של קבוצת קואורדינטות של קווי רוחב ואורך (המרת קואורדינטות לכתובות).
- הגבלת בקשה להמרת כתובות לקואורדינטות (geocoding) כדי להחזיר תוצאות בתוך אזור תצוגה ספציפי. הערה: ב-Geocoding API v4, הפרמטר locationBias נותן עדיפות לתוצאות באזור התצוגה שצוין, במקום להגביל אותן באופן מחמיר.
- להגביל בקשה להמרת כתובות לקואורדינטות או להמרת קואורדינטות לכתובות, כך שיוחזרו רק תוצאות באזור, במדינה או במיקוד ספציפיים. הערה: בגרסה 4 של Geocoding API, הפרמטר regionCode נותן עדיפות לתוצאות מאזור CLDR מסוים, במקום להגביל אותן באופן מוחלט. כדי לסנן רכיבים לפי מדינה או מיקוד בגרסה 3 הקודמת, אפשר לעיין בכתובת https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- הגבלת בקשה להמרת קואורדינטות לכתובות כך שיוחזרו רק תוצאות של סוגי כתובות מסוימים. הערה: ב-Geocoding API v4, הפרמטר types מסנן את התוצאות של המרת קואורדינטות לכתובות לפי סוג הכתובת אחרי החיפוש, במקום להגביל את החיפוש הבסיסי.
- החזרת מידע על הקרבה של כתובת לאתרים או לאזורים.
- החזרת מידע על הקרבה לאזורים או לנקודות ציון לפי קבוצה של קואורדינטות של קווי רוחב ואורך.
- החזרת מידע על הקרבה לאזורים או לנקודות ציון של מזהה מקום ב-Google.
- החזרת הכתובת של מזהה מקום ב-Google.
- החזרת הקואורדינטות של קו הרוחב/קו האורך של מתאר בניין לפי כתובת.
- החזרת הקואורדינטות של קו הרוחב/האורך של קווי המתאר של מבנה עבור קבוצה של קואורדינטות של קו רוחב/אורך.
- החזרת הקואורדינטות של קו הרוחב/קו האורך של קווי המתאר של מבנה לפי מזהה מקום ב-Google.
- החזרת הקואורדינטות של קו הרוחב/קו האורך של כניסה לבניין בכתובת מסוימת.
- החזרת הקואורדינטות של קו הרוחב/האורך של כניסה לבניין עבור קבוצה של קואורדינטות של קו רוחב/אורך.
- החזרת הקואורדינטות של קו הרוחב/קו האורך של כניסה לבניין עבור מזהה מקום ב-Google.