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

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

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

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

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

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

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

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

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

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

שדה גרסה 3 שדה v4 הערות
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)

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

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

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

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

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

שדה גרסה 3 שדה v4 הערות
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 של מתארי כתובות

אם אתם משתמשים ב-address_descriptor כדי לקבל מידע נוסף על מיקום באמצעות Geocoding v3, אתם צריכים לעבור לשימוש בשדה landmarks של SearchDestinationsResponse.

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

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

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

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

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

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

שדה גרסה 3 שדה v4 הערות
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 גרסה 3 מוחלפות בשיטה SearchDestinations של Geocoding API גרסה 4:

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

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

כניסות

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

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

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

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

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

  • ‫displayName – זהו שדה אופציונלי חדש שיכלול שם קריא של נקודת הניווט, לדוגמה 'שדרת 5'.
  • ‫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.

ל-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.

הדיוק של התוצאות

ב-Geocoding API v3, השדה location_type בגיאומטריה של התגובה הצביע על רמת הדיוק של התוצאות, וחלק מהלקוחות דירגו או סיננו תוצאות על סמך הערכים האלה (ROOFTOP,‏ RANGE_INTERPOLATED,‏ GEOMETRIC_CENTER ו-APPROXIMATE). בהעברות רגילות של Geocoding API v4, השדה הזה נקרא granularity.

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

  • אין צורך בסינון ידני בצד הלקוח: בעוד שגיאו-קידוד רגיל מספק כמה תוצאות ברמות גרנולריות שונות, השיטה SearchDestinations מצמצמת את העמימות על ידי פתרון ליעד יחיד ואופטימלי ככל האפשר. כך הלקוחות לא צריכים לסנן לפי סוג המיקום כדי לקבוע איזו תוצאה היא הטובה ביותר.
  • מידע מרחבי שמיוצג על ידי סוג המבנה ומצולעים לתצוגה: הגיאומטריה והמבנה המרחביים מסומנים על ידי:
    • הערך displayPolygon (לגיאומטריה מדויקת).
    • השדה structureType באובייקט placeView.
  • מיפוי סוגי המבנה:
    • ערך structureType של POINT, BUILDING או SECTION בדרך כלל תואם למה שנקרא בעבר ROOFTOP.
    • בדרך כלל, ציון של structureType מתוך GROUNDS מתאים ל-GEOMETRIC_CENTER.

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

השיטה 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/v4/geocode/destinations

שיקולי אבטחה

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

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

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

חלופות לצרכים בצד הלקוח

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