מעבר מגרסה 3 לגרסה 4 של Geocoding

מפתחים באזור הכלכלי האירופי (EEA)

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

ב-Geocoding API v4 הוספנו כמה נקודות קצה חדשות שמחליפות את הפונקציונליות של גרסה 3 של ה-API. במדריך הזה מוסבר איך להעביר את האפליקציה לשימוש בנקודות הקצה החדשות בגרסה 4.

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

הערה: במהלך תקופת התצוגה המקדימה, השיטות של Geocoding API v4 מוגבלות ל-25 שאילתות לשנייה (QPS). למידע על שליחת בקשה להגדלת המכסה, אפשר לעיין במאמר איך רואים ומנהלים את המכסות ולבחור באפשרות Geocoding API כשירות.

מעבר מגרסה 3 של המרת קואורדינטות לכתובות

אם אתם משתמשים ב-Geocoding כדי לבצע קידוד גיאוגרפי של כתובות, אתם צריכים לעבור לנקודת הקצה Geocode an address בגרסה 4, שמקבלת בקשת GET.

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

אזהרה: בכל נקודות הקצה בגרסה 4, שמות השדות מעוצבים באמצעות lower camel case (למשל, addressComponents), בניגוד לנקודות הקצה בגרסה 3, שבהן נעשה שימוש ב-snake case (למשל, address_components). תשובות RPC ממשיכות להשתמש ב-snake case בגרסה 4, כמו בגרסה 3.

שינויים בפרמטרים של בקשות

פרמטר v3	פרמטר v4	הערות
address, components	address	כתובת לא מובנית (גרסה 3 address) מועברת עכשיו בנתיב כתובת ה-URL. מסנני רכיבים (גרסה 3 components) מועברים עכשיו כפרמטרים של שאילתות address.*.
bounds	locationBias.rectangle	השם השתנה; המבנה השתנה לאובייקט.
language	languageCode	השם שונה.
region	regionCode	השם שונה.
extra_computations	הוסר

שינויים בשדה התשובה

שדה בגרסה 3	שדה בגרסה 4	הערות
status, error_message	הוסר	‫v4 משתמש בקודי מצב HTTP ובגופי שגיאות.
results.address_components.long_name / results.address_components.short_name	results.addressComponents.longText / results.addressComponents.shortText	השם שונה.
results.geometry.location_type	results.granularity	השם שונה.
results.geometry.location	results.location	שמות השדות: lat/lng -> latitude/longitude.
results.geometry.viewport	results.viewport	שמות השדות: northeast/southwest -> high/low.
results.postcode_localities	results.postalCodeLocalities	השם שונה. הערך הזה מוחזר עכשיו עבור יישוב אחד או יותר (נדרשת גרסה 3 ומעלה).
results.partial_match	הוסר
חדש	results.addressComponents.languageCode	השפה של רכיב הכתובת הספציפי.
חדש	results.bounds	גבולות מפורשים באמצעות high/low.
חדש	results.place	שם המשאב של המקום.
חדש	results.postalAddress	אובייקט PostalAddress מובנה.

מעבר מגרסה 3 של Reverse Geocoding

אם אתם משתמשים ב-Reverse Geocoding כדי להפוך קואורדינטות לכתובות, אתם צריכים לעבור לנקודת הקצה Reverse geocode a location בגרסה 4, שמקבלת בקשת GET.

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

אזהרה: בכל נקודות הקצה בגרסה 4, שמות השדות מעוצבים באמצעות lower camel case (למשל, addressComponents), בניגוד לנקודות הקצה בגרסה 3, שבהן נעשה שימוש ב-snake case (למשל, address_components). תשובות RPC ממשיכות להשתמש ב-snake case בגרסה 4, כמו בגרסה 3.

שינויים בפרמטרים של בקשות

פרמטר v3	פרמטר v4	הערות
language	languageCode	השם שונה.
region	regionCode	השם שונה.
result_type	types	שונה השם; נעשה שימוש בפרמטרים חוזרים של שאילתה.
location_type	granularity	שונה השם; נעשה שימוש בפרמטרים חוזרים של שאילתה.
extra_computations	הוסר

שינויים בשדה התשובה

שדה בגרסה 3	שדה בגרסה 4	הערות
status, error_message	הוסר	‫v4 משתמשת בקודי מצב HTTP ובגופי שגיאות.
results.address_components.long_name / results.address_components.short_name	results.addressComponents.longText / results.addressComponents.shortText	השם שונה.
results.geometry.location_type	results.granularity	השם שונה.
results.geometry.location	results.location	שמות השדות: lat/lng -> latitude/longitude.
results.geometry.viewport	results.viewport	שמות השדות: northeast/southwest -> high/low.
חדש	results.addressComponents.languageCode	השפה של רכיב הכתובת הספציפי.
חדש	results.bounds	גבולות מפורשים באמצעות high/low.
חדש	results.place	שם המשאב של המקום.
חדש	results.postalAddress	אובייקט PostalAddress מובנה.

מעבר מגרסה 3 של Place Geocoding

אם אתם משתמשים ב-place_id כדי לקבל את הכתובת של מזהה מקום ספציפי באמצעות Geocoding v3, אתם צריכים לעבור לנקודת הקצה Place Geocoding v4, שמקבלת בקשת GET.

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

אזהרה: בכל נקודות הקצה בגרסה 4, שמות השדות מעוצבים באמצעות lower camel case (למשל, addressComponents), בניגוד לנקודות הקצה בגרסה 3, שבהן נעשה שימוש ב-snake case (למשל, address_components). תשובות RPC ממשיכות להשתמש ב-snake case בגרסה 4, כמו בגרסה 3.

שינויים בפרמטרים של בקשות

פרמטר v3	פרמטר v4	הערות
place_id	שדה place בפרוטוקול הבקשה	מזהה המקום מסופק עכשיו כפרמטר נתיב places/{place}, לדוגמה: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. השדה הזה ממופה לשדה המקום בבקשה הבסיסית.
language	languageCode	השם שונה.
region	regionCode	השם שונה.

שינויים בשדה התשובה

שדה בגרסה 3	שדה בגרסה 4	הערות
status, error_message	הוסר	‫v4 משתמשת בקודי מצב HTTP ובגופי שגיאות.
results	(root)	בגרסה 4 מוחזר אובייקט תוצאה יחיד, ולא מערך results.
results.address_components.long_name / results.address_components.short_name	addressComponents.longText / addressComponents.shortText	השם שונה.
results.geometry.location_type	granularity	השם שונה.
results.geometry.location	location	שמות השדות: lat/lng -> latitude/longitude.
results.geometry.viewport	viewport	שמות השדות: northeast/southwest -> high/low.
results.postcode_localities	postalCodeLocalities	השם שונה. הערך הזה מוחזר עכשיו עבור יישוב אחד או יותר (נדרשת גרסה 3 ומעלה).
חדש	addressComponents.languageCode	השפה של רכיב הכתובת הספציפי.
חדש	bounds	גבולות מפורשים באמצעות high/low.
חדש	place	שם המשאב של המקום.
חדש	postalAddress	אובייקט PostalAddress מובנה.

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

התכונות הבאות ב-Geocoding API v3 מוחלפות בנקודת הקצה SearchDestinations של Geocoding API v4:

• כניסות
• נקודות ניווט
• יצירת נקודות עיקריות
• שטחים

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

כניסות

כדי לקבל את הכניסות שמשויכות לdestination, משתמשים בשדה destination.entrances.

שימו לב: הפורמט של entrance שונה מעט מפורמט הכניסה ב-Geocoding API גרסה 3. לכל כניסה ב-destination.entrances יש את השדות הבאים:

• ‫displayName – זהו שדה אופציונלי חדש שיופיע בו שם הכניסה שקריא לבני אדם, למשל Gate B.
• ‫location – זהו מיקום מהסוג LatLng, ששונה מהפורמט שבו נעשה שימוש ב-Geocoding API v3.
• ‫tags – זהה לשדה tags של הכניסות מ-Geocoding API v3.
• ‫place – מקביל לשדה buildingPlaceId של הכניסות מ-Geocoding API v3. עם זאת, מזהה המקום בשדה הזה יכול להיות של מקום מכל סוג, לא רק של בניין.

נקודות ניווט

כדי לקבל את נקודות הניווט שמשויכות ל-destination, משתמשים בשדה destination.navigationPoints.

שימו לב שהפורמט של navigationPoint שונה מעט מהפורמט של נקודת ניווט ב-Geocoding API v3. כל נקודת ניווט ב-destination.navigationPoints כוללת את השדות הבאים:

• ‫displayName – זהו שדה אופציונלי חדש שיכלול שם קריא של נקודת הניווט, לדוגמה 'שדרת האפשרויות'.
• ‫location – זהו מיקום מהסוג LatLng, ששונה מהפורמט שבו נעשה שימוש ב-Geocoding API v3.
• ‫travelModes – דומה לשדה restrictedTravelModes של נקודות הניווט מ-Geocoding API גרסה 3. הערכים האפשריים של ה-enum זהים, וההבדל היחיד הוא שעכשיו השדה הזה מייצג את אמצעי התחבורה המקובלים לנקודת הניווט, ולא את אמצעי התחבורה המוגבלים.
• ‫usage – זהו שדה חדש שמכיל את תרחישי השימוש שנתמכים על ידי נקודת הניווט. שימו לב שלרוב נקודות הניווט יהיה שימוש UNKNOWN, אבל זה לא בהכרח אומר שהשימוש בנקודת הניווט מוגבל בצורה כלשהי.

יצירת נקודות עיקריות

כדי לקבל את קווי המתאר של הבניין שמשויכים ל-destination, צריך להשתמש בשדה destination של האובייקטים placeView ב-destination שמייצגים בניינים.displayPolygon לכל placeView, אפשר לבדוק אם מדובר בבניין באמצעות השדה placeView.structureType. אם סוג המבנה הוא BUILDING, אפשר לקבל את המתאר מהשדה placeView.displayPolygon. ב-placeView יהיו גם שדות נוספים של הבניין שלא היו ב-Geocoding API v3.

הערה: רוצים רק את הפוליגון של הבניין במיקום מסוים? אפשר להשתמש בפרמטר placeFilter בבקשה כדי לצמצם את התוצאות. כדי להחזיר רק תוצאות של בניינים, צריך להגדיר את structureType ל-"BUILDING" בתוך placeFilter. אם חשוב לכם לקבל פוליגון (גם למיקומים בלי כתובות מדויקות), צריך להגדיר את addressability לערך "ANY" ב-placeFilter כדי לקבל את הפוליגון הכי מדויק שאפשר.

דוגמה

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}
  

ל-destination יכול להיות אובייקט placeView שמייצג בניין בשדות הבאים:

• ‫destination.primary – זה המקום העיקרי של היעד.
• ‫destination.containingPlaces – זהו שדה חוזר שיכול להכיל מקומות גדולים יותר ש "מכילים" את המקום הראשי. לדוגמה, אם המקום הראשי הוא subpremise, בדרך כלל containingPlaces יכיל את placeView שמייצג את הבניין.
• ‫destination.subDestinations – זהו שדה חוזר שיכול להכיל יעדי משנה של המקום הראשי. לדוגמה, יחידות דיור נפרדות בבניין. בדרך כלל לא יהיה בשדה הזה placeView שמייצג בניין.

שימו לב שהפורמט של placeView.displayPolygon זהה לפורמט של מתאר הבניין ב-Geocoding API v3, שהוא פורמט GeoJSON, באמצעות פורמט RFC 7946.

שטחים

בדומה ליצירת מתארים, כדי לקבל את השטחים שמשויכים ל-destination, צריך להשתמש בשדה displayPolygon של אובייקטים מסוג placeView ב-destination שמייצגים שטחים. לכל placeView, אפשר לבדוק אם הוא עילה באמצעות השדה placeView.structureType. אם סוג המבנה הוא GROUNDS, אפשר לקבל את המתאר מהשדה placeView.displayPolygon. ב-placeView יהיו גם שדות נוספים לסיבות שלא היו ב-Geocoding API v3.

ל-destination יכול להיות אובייקט placeView שמייצג את הסיבות בשדות הבאים:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

שימו לב שהפורמט של placeView.displayPolygon זהה לפורמט של המתאר של השטח ב-Geocoding API v3, שהוא פורמט GeoJSON, באמצעות פורמט RFC 7946.

שימוש במסכת שדות כדי לבקש את התכונות האלה

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

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations