Destination הוא מיקום או מקום ספציפיים שמשתמש מתכוון להגיע אליהם או לנווט אליהם. Destination כולל גם אוסף של מידע שקשור למיקום או למקום, כמו נקודות ניווט, אתרים ידועים, כניסות ומתארים של בניינים.
ה-method SearchDestinations של Geocoding API מאפשרת לאחזר מידע מפורט על יעדים שונים על סמך קריטריונים שונים של קלט, כמו כתובת, מזהה מקום או קואורדינטות של קו רוחב וקו אורך.
בקשה לחיפוש יעדים
בקשה לחיפוש יעדים היא בקשת POST לכתובת URL בפורמט הבא:
https://geocode.googleapis.com/v4/geocode/destinations
מעבירים את כל הפרמטרים בגוף הבקשה בפורמט JSON או בכותרות כחלק מבקשת ה-POST. לדוגמה:
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
יש 3 דרכים לציין את המיקום שבו רוצים לחפש יעד:
- כתובת
- מזהה מקום
- קואורדינטות של אורך ורוחב
חיפוש יעד לפי כתובת
אפשר לציין את הכתובת כמחרוזת לא מובנית. המרת כתובת לקואורדינטות לא פותרת קואורדינטות של קווי אורך ורוחב, או מחרוזות לא מובנות אחרות שלא מייצגות כתובת. בקשות שמשתמשות במחרוזות כאלה לא נתמכות, ויכול להיות שהן יובילו לתגובות שגיאה או להתנהגות לא מוגדרת. דוגמאות לשאילתות לא נתמכות:
| סוג השאילתה | דוגמה |
|---|---|
| קואורדינטות של קווי רוחב ואורך. במקום זאת, השתמשו בשאילתת מיקום. | "37.422131,-122.084801" |
| יותר מדי מושגים או אילוצים, כמו שמות של כמה מקומות, כבישים או ערים בשאילתה אחת | "Market Street San Francisco San Jose Airport" |
| רכיבים של כתובת למשלוח דואר שלא מיוצגים במפות Google |
"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco" |
| שמות של עסקים, רשתות או קטגוריות בשילוב עם מיקומים שבהם הישויות האלה לא זמינות | "Tesco near Dallas, Texas" |
| שאילתות דו-משמעיות עם כמה פרשנויות | "Charger drop-off" |
| שמות היסטוריים שכבר לא בשימוש | "Middlesex United Kingdom" |
| רכיבים או כוונות שאינם גיאוגרפיים | "כמה סירות יש בנמל ונטורה?" |
| שמות לא רשמיים או שמות שנועדו להאדיר את בעליהם |
"The Jenga" "The Helter Skelter" |
| ישויות פוליטיות גדולות (ערים, מדינות, מדינות) |
"New York City" "California" "USA" |
| מסלולים בלי כתובות ספציפיות |
"1st Ave., NYC, NY" "I-95" |
curl -X POST -d '{
"addressQuery": {
"addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
או בתור
postalAddress:
curl -X POST -d '{
"addressQuery": {
"address": {
"addressLines": ["601 S Bernardo Ave"],
"locality": "Sunnyvale",
"postalCode": "94087",
"administrativeArea": "CA",
"regionCode": "US"
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
בדרך כלל משתמשים בפורמט postalAddress כשמעבדים רכיבי כתובת שמתועדים בטופס HTML.
חיפוש יעד לפי מזהה מקום
אפשר לאחזר יעד באמצעות מזהה מקום:
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
מזהי מקומות נתמכים
השיטה Search Destinations פועלת בצורה הטובה ביותר עם מזהי מקומות שמייצגים יעדים ספציפיים שאפשר לנווט אליהם. בדרך כלל יש תמיכה במזהי מקומות מסוגים כמו establishment, point_of_interest, premise, street_address ו-subpremise. מזהי מקומות שלא מייצגים מיקומים נפרדים, כמו אלה שמשוערים מטווחים של כתובות (לדוגמה, '10-20 Main St'), קטעים של מסלול ללא מספר ספציפי או קודי פלוס, לא נתמכים. בנוסף, אין תמיכה במזהי מקומות של תוצאות שהשטח שלהן גדול מדי (לדוגמה, "האוקיינוס השקט").
שימוש בהשלמה אוטומטית (חדש) עם יעדים לחיפוש
כדי לוודא תאימות, צריך להשתמש ב-Autocomplete (חדש) כדי למצוא מזהי מקומות לשימוש עם Search Destinations. כשמשתמשים בהשלמה אוטומטית (חדשה), צריך לסנן את התוצאות לפי סוג באמצעות הפרמטר includedPrimaryTypes. התכונה "חיפוש יעדים" תומכת במזהי מקומות שמוחזרים על ידי ההשלמה האוטומטית (חדש) באמצעות המסנן המומלץ הבא:
"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]
בנוסף, לא צריך להגדיר את הדגל include_pure_service_area_businesses לערך true בבקשה של ההשלמה האוטומטית (חדש).
חיפוש יעד לפי מיקום
אפשר לחפש יעדים עם קואורדינטות של קו אורך וקו רוחב:
curl -X POST -d '{
"locationQuery": {
"location": {
"latitude": 37.37348780,
"longitude": -122.05678064
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations
שימוש ב-OAuth כדי לשלוח בקשה
גרסה 4 של Geocoding API תומכת ב-OAuth 2.0 לאימות. כדי להשתמש ב-OAuth עם Geocoding API, צריך להקצות לטוקן OAuth את ההיקף הנכון. Geocoding API תומך בהיקפי ההרשאות הבאים לשימוש בשיטה Destinations:
https://www.googleapis.com/auth/maps-platform.geocode— לשימוש בכל ה-methods של Geocoding API.
אפשר גם להשתמש בהיקף הכללי https://www.googleapis.com/auth/cloud-platform לכל השיטות של Geocoding API. ההיקף הזה שימושי במהלך הפיתוח, אבל לא בסביבת הייצור, כי הוא היקף כללי שמאפשר גישה לכל השיטות.
מידע נוסף ודוגמאות זמינים במאמר שימוש ב-OAuth.
תגובה של חיפוש יעדים
התגובה של Search Destinations מספקת הקשר עשיר וממוקד לקהילה לגבי המיקום.
האובייקטים PlaceView בתגובה של Search Destinations (כמו primary, פריטים ב-containingPlaces ו-landmarks) משתמשים בשדות כדי לציין את סוג המקום:
-
types: מערך של מחרוזות שמציינות את סוגי המקומות. -
primaryType: מחרוזת שמציינת את הסוג העיקרי של המקום.
ערכי המחרוזת האפשריים של types ושל primaryType נלקחים מטבלה א' וטבלה ב' בדף "סוגי מקומות (חדש)".
בקטע הזה מתוארים שדות התגובה העיקריים. פרטים מלאים על כל שדות התגובה מופיעים בחומר העזר בנושא API.
primary
המקום העיקרי שזוהה על ידי השאילתה בבקשה.
addressComponents
מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.
כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:
-
types[]הוא מערך שמציין את סוג רכיב הכתובת. לרשימת הסוגים הנתמכים -
longTextהוא התיאור המלא או השם של רכיב הכתובת כפי שמוחזר על ידי כלי להמרת כתובות לקואורדינטות (geocoder). -
shortTextהוא שם טקסטואלי מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של מדינת אלסקה יכול לכלולlongTextעם הערך Alaska ו-shortTextעם הערך AK, באמצעות הקיצור בן שתי האותיות של המיקוד. -
languageCodeהיא השפה שבה נעשה שימוש כדי לעצב את הרכיב הזה, בסימון CLDR.
containingPlaces
יחידות גדולות יותר שהיעד הראשי הוא חלק מהן (לדוגמה, קניון שכולל חנות).
subDestinations
מיקומים ספציפיים יותר ביעד הראשי (למשל, דירות בבניין).
entrances
האובייקטים במערך entrances[] כוללים את השדות הבאים:
locationזוג קואורדינטות יחיד של קו רוחב/קו אורך שמגדיר את המיקום של נקודת כניסה ויציאה למקום.
entrance_tags[]מערך של תגי כניסה שמתארים את מאפייני הכניסה. הערך הבא נתמך:
"PREFERRED"
המאפיין הזה מציין שהכניסה הזו כנראה מספקת גישה פיזית למקום שהוחזר. למקום יכולות להיות כמה כניסות מועדפות. אם תג הכניסה לא מופיע, זה אומר שהכניסה נמצאת פיזית באותו בניין, אבל לא בהכרח מאפשרת גישה למקום.
לדוגמה, אם המקום שמוחזר הוא מסעדה במרכז קניות, ערכי
"PREFERRED"הכניסות יהיו אלה שמובילות אל המסעדה עצמה, ואילו ערכי הכניסות האחרים שמוחזרים יהיו כניסות אחרות לבניין, כמו כניסות למסעדות אחרות במרכז הקניות.אם המקום שמוחזר הוא בניין, הכניסות של
"PREFERRED"יהיו אלה שמובילות לחלק הראשי של הבניין. לדוגמה, במרכז קניות, הכניסות מסוג"PREFERRED"יהיו אלה שמאפשרות גישה לאזור המבואה הראשי, אבל אם כניסה מסוימת מאפשרת גישה רק לחנות בצד הבניין, היא לא תהיה כניסה מסוג"PREFERRED".streetViewThumbnailוגםstreetViewAnnotationפרמטרים של Street View Static API, שמאפשרים להציג תמונות רלוונטיות של המיקומים האלה. מידע נוסף על השדות האלה
structureType
סוג המבנה שהמקום הזה מייצג.
POINTמיקום של נקודה.
SECTIONחלק משנה של בניין.
BUILDINGבניין.
GROUNDSאזור גדול שבדרך כלל מכיל כמה מבנים, כמו קמפוס של אוניברסיטה, מתחם דירות או קניון.
navigationPoints
השדה navigationPoints בתשובה של המרת הכתובות לקואורדינטות מכיל רשימה של נקודות שמועילות לניווט למקום. במילים אחרות, צריך להשתמש בהם כנקודות התחלה או כנקודות סיום כשמגדירים מסלול ברשת כבישים מהמקום או אל המקום.
כל נקודת ניווט מכילה את הערכים הבאים:
-
navigationPointTokenהוא אסימון שמכיל את המידע ההקשרי בשדהnavigationPoints. אתם יכולים לשלוח את הטוקן הזה לממשקי API של ניתוב וניווט כדי לשפר את חוויית הניתוב והנהיגה באפליקציה. מידע נוסף זמין במאמר ניתוב באמצעות טוקנים של נקודות ניווט. - השדה
locationמכיל את ערכי קו הרוחב וקו האורך של נקודת הניווט. המיקום הזה תמיד יהיה קרוב מאוד לרשת הכבישים, והוא מייצג נקודת עצירה או נקודת התחלה אידיאלית לניווט אל מקום מסוים וממנו. הנקודה מוסטת בכוונה מעט מקו האמצע של הכביש כדי לסמן בבירור את הצד של הכביש שבו המקום ממוקם. -
travelModesהיא רשימה של אמצעי הגעה שאפשר להגיע איתם לנקודת הניווט:-
"DRIVE"הוא אמצעי התחבורה שמתאים למסלול נסיעה. -
"WALK"הוא אמצעי התחבורה שמתאים להוראות הגעה בהליכה.
-
-
usagesהיא רשימה של שימושים שנתמכים על ידי נקודת הניווט. השימושים יכולים להיות:"DROPOFF""PICKUP""PARKING"
לגבי איסוף והחזרה של רכב, משתמשים בנקודת הניווט שבה אמצעי התחבורה הוא DRIVE והשימוש הוא PICKUP או DROPOFF. אם אין נקודות איסוף או הורדה, צריך להשתמש בנקודת הניווט העליונה ברכב.
streetViewThumbnailו-entranceAnnotationמספקים פרמטרים ל-Street View Static API, שמאפשרים להציג תמונות רלוונטיות למיקומים האלה. מידע נוסף על השדות האלה
- השדה
altitude_metersמכיל את הגובה של נקודת הניווט במטרים ביחס לאליפסואיד WGS-84. במקרים שבהם יש מקטעי כביש שמוערמים אנכית, צריך להשתמש בשדהaltitude_metersכדי לבחור את מקטע הכביש שהכי מתאים לניווט במערכת.
landmarks
מקומות בולטים בקרבת מקום, כדי לעזור למשתמשים להבין את הסביבה של היעד.
arrivalSummary
תובנות מבוססות-AI שיעזרו לכם להגיע ליעד. סיכומים מבוססי-AI
parkingOptions
פרטים מפורטים על החנייה.
פורמט התשובה
הפונקציה SearchDestinations מחזירה SearchDestinationsResponse בפורמט JSON הבא:
{ "destinations": [ { "primary": { "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w", "displayName": { "text": "Arby's", "languageCode": "en" }, "primaryType": "fast_food_restaurant", "types": [ "fast_food_restaurant", "sandwich_shop", "deli", "meal_takeaway", "food_delivery", "american_restaurant", "restaurant", "food_store", "store", "food", "point_of_interest", "establishment" ], "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "601 S Bernardo Ave" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3734545, "longitude": -122.05693269999998 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.056930138027, 37.3735253692531 ], [ -122.056960139391, 37.3735372663597 ], [ -122.056994129366, 37.3734828786847 ], [ -122.056969677395, 37.3734731161089 ], [ -122.057061762447, 37.3733261309656 ], [ -122.056979388817, 37.3732935577128 ], [ -122.056798860285, 37.3735818838642 ], [ -122.056875858081, 37.3736121235316 ], [ -122.056930138027, 37.3735253692531 ] ] ] } }, "containingPlaces": [ { "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw", "displayName": { "text": "Cherry Chase Shopping Center", "languageCode": "en" }, "primaryType": "shopping_mall", "types": [ "shopping_mall", "point_of_interest", "establishment" ], "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1020", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "663 S Bernardo Ave" ] }, "structureType": "GROUNDS", "location": { "latitude": 37.3731231, "longitude": -122.0578211 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.057112227103, 37.3714618008523 ], [ -122.057076849821, 37.3715743611411 ], [ -122.056963607756, 37.3719081793948 ], [ -122.056865279559, 37.3722026053835 ], [ -122.056687872374, 37.3727258358476 ], [ -122.056580005889, 37.3730511370747 ], [ -122.056498845827, 37.3732994782583 ], [ -122.056338259713, 37.3737878663325 ], [ -122.056618678291, 37.373887693582 ], [ -122.056912102521, 37.3740010327191 ], [ -122.057532418159, 37.3742476426462 ], [ -122.057673926626, 37.3742441740031 ], [ -122.057735663106, 37.3742328516943 ], [ -122.057766531332, 37.3742220604378 ], [ -122.057797572967, 37.37420520725 ], [ -122.057828267759, 37.3741852342085 ], [ -122.058060299297, 37.3740060842535 ], [ -122.058199726081, 37.3737861673422 ], [ -122.05836707267, 37.373524542556 ], [ -122.058569622393, 37.3732018598683 ], [ -122.0587638478, 37.3728890198039 ], [ -122.058934661823, 37.3726036257774 ], [ -122.059164956851, 37.3722498383629 ], [ -122.058997784906, 37.3721804442035 ], [ -122.057936479838, 37.3717605636234 ], [ -122.057495827092, 37.3715860151634 ], [ -122.057112227103, 37.3714618008523 ] ] ] } } ], "landmarks": [ { "place": { "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg", "displayName": { "text": "Chase Bank", "languageCode": "en" }, "primaryType": "bank", "types": [ "bank", "atm", "finance", "point_of_interest", "establishment" ], "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1234 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.373579, "longitude": -122.05752700000001 } }, "relationalDescription": { "text": "Near Chase Bank", "languageCode": "en" }, "tags": [ "ARRIVAL", "ADDRESS" ], "straightLineDistanceMeters": 61.182193756103516, "travelDistanceMeters": 63.075645446777344 }, { "place": { "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14", "displayName": { "text": "Safeway", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "butcher_shop", "florist", "deli", "supermarket", "bakery", "food_delivery", "market", "manufacturer", "food_store", "store", "food", "service", "point_of_interest", "establishment" ], "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "639 S Bernardo Ave" ] }, "structureType": "POINT", "location": { "latitude": 37.3727912, "longitude": -122.0581172 } }, "relationalDescription": { "text": "Around the corner from Safeway", "languageCode": "en" }, "tags": [ "ARRIVAL", "ADDRESS" ], "straightLineDistanceMeters": 158.65606689453125, "travelDistanceMeters": 131.1669921875 }, { "place": { "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk", "displayName": { "text": "Oil Changers", "languageCode": "en" }, "types": [ "car_repair", "service", "point_of_interest", "establishment" ], "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1240 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3743054, "longitude": -122.0584272 } }, "relationalDescription": { "text": "Down the road from Oil Changers", "languageCode": "en" }, "tags": [ "ARRIVAL" ], "straightLineDistanceMeters": 140.52459716796875, "travelDistanceMeters": 143.24220275878906 }, { "place": { "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0", "displayName": { "text": "Apni Mandi Farmers Market Sunnyvale", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "cake_shop", "supermarket", "asian_grocery_store", "indian_restaurant", "meal_takeaway", "bakery", "manufacturer", "wholesaler", "restaurant", "food_store", "store", "food", "point_of_interest", "establishment" ], "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1056", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1111 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3737199, "longitude": -122.0522958 } }, "relationalDescription": { "text": "Near Apni Mandi Farmers Market Sunnyvale", "languageCode": "en" }, "tags": [ "ADDRESS" ], "straightLineDistanceMeters": 410.37435913085938, "travelDistanceMeters": 479.49893188476562 }, { "place": { "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs", "displayName": { "text": "Starbird Chicken", "languageCode": "en" }, "primaryType": "chicken_restaurant", "types": [ "chicken_restaurant", "fast_food_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1028", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1241 W El Camino Real" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3746764, "longitude": -122.05708860000001 }, "displayPolygon": { "coordinates": [ [ [ -122.057003840785, 37.3747648209809 ], [ -122.057136852459, 37.3747919153144 ], [ -122.057205005705, 37.3745815131859 ], [ -122.057071994114, 37.3745544186944 ], [ -122.057003840785, 37.3747648209809 ] ] ], "type": "Polygon" } }, "relationalDescription": { "text": "Near Starbird Chicken", "languageCode": "en" }, "tags": [ "ADDRESS" ], "straightLineDistanceMeters": 87.348007202148438, "travelDistanceMeters": 214.08084106445312 } ], "entrances": [ { "location": { "latitude": 37.3735328, "longitude": -122.05694879999999 }, "tags": [ "PREFERRED" ], "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w" } ], "navigationPoints": [ { "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4", "location": { "latitude": 37.3738659, "longitude": -122.05693620000001 }, "travelModes": [ "DRIVE", "WALK" ], "usages": [ "PARKING" ] } ] } ] }
פרמטרים נדרשים
- אחד מ-3 הפרמטרים הבאים חייב להיות בבקשת ה-API, שמציינת את הכתובת, המקום או המיקום לחיפוש יעד:
-
addressQuery– הכתובת שרוצים לחפש. -
place– מזהה המקום של המקום שרוצים לחפש. -
locationQuery– הקואורדינטות של קווי הרוחב והאורך של המיקום שרוצים לחפש.
-
FieldMask
כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים מסכת שדות תגובה. מעבירים את מסכת שדות התגובה ל-method באמצעות הפרמטר של כתובת ה-URL
$fieldsאוfields, או באמצעות כותרת ה-HTTPX-Goog-FieldMask. לדוגמה, הבקשה הבאה תחזיר רק את הכניסות, נקודות הניווט ומזהה המקום של היעד הראשי.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.place" \ https://geocode.googleapis.com/v4/geocode/destinationsאין רשימת ברירת מחדל של שדות שמוחזרים בתשובה. אם משמיטים את מסכת השדה, השיטה מחזירה שגיאה. מגדירים את מסכת השדות ל-
*כדי להחזיר את כל השדות. פרטים נוספים מופיעים במאמר בנושא בחירת שדות להחזרה.
פרמטרים אופציונליים
-
travelModes
מציין אילו סוגים של
navigationPointsיוחזרו. המערכת תסנן נקודות ניווט של אמצעי תחבורה אחרים. אםtravelModesלא מוגדר, אפשר להחזיר נקודות ניווט של כל אמצעי התחבורה. languageCode
השפה שבה התוצאות יוחזרו.
- כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
-
אם לא מספקים את
languageCode, ה-API משתמש כברירת מחדל בשפה ובכתב המקומיים של המיקום. אם תציינו קוד שפה לא חוקי, ה-API יחזיר שגיאתINVALID_ARGUMENT. - הממשק API עושה כמיטב יכולתו כדי לספק כתובת רחוב שקלה לקריאה גם למשתמש וגם לתושבים המקומיים. כדי להשיג את המטרה הזו, הוא מחזיר כתובות רחוב בשפה המקומית, בתעתיק לכתב שניתן לקריאה על ידי המשתמש אם יש צורך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מהרכיב הראשון.
- אם השם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.
- השפה המועדפת משפיעה קצת על קבוצת התוצאות שה-API בוחר להחזיר ועל הסדר שבו הן מוחזרות. כלי להמרת כתובות לקואורדינטות (geocoder) מפרש קיצורים בצורה שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת.
regionCode
קוד האזור, שמוגדר כערך קוד CLDR באורך שני תווים. אין ערך ברירת מחדל. רוב הקודים ב-CLDR זהים לקודים ב-ISO 3166-1.
כשמבצעים המרה של כתובת לקואורדינטות (geocoding), כלומר המרה קדימה, הפרמטר הזה יכול להשפיע על התוצאות מהשירות, אבל לא להגביל אותן באופן מלא לאזור שצוין. כשממירים כתובת של מיקום או מקום לקואורדינטות (geocoding), המרת קואורדינטות לכתובות (reverse geocoding) או המרת כתובות של מקומות לקואורדינטות, אפשר להשתמש בפרמטר הזה כדי לעצב את הכתובת. בכל המקרים, הפרמטר הזה יכול להשפיע על התוצאות בהתאם לדין החל.
-
placeFilter
מאפשר לסנן את התוצאות של חיפוש ב-
locationQueryכדי לעמוד בדרישות שלכם, למשל להחזיר רק יעדים שהם בניינים או רק יעדים שיש להם כתובות ברורות.סינון לפי רמת פירוט מבנית
המסנן
structureTypeמאפשר לציין את סוג המבנים שמוחזרים על ידי השאילתה:- בידוד מבנים: אפשר להשתמש ב-
"structureType": "BUILDING"כדי להציג קווי מתאר של מבנים במפה או לקבל פרטים על מבנה ספציפי. - הסבר על מתחמים: משתמשים ב-
"structureType": "GROUNDS"כדי לוודא שהתוצאה הראשית היא המתחם כולו. האפשרות הזו שימושית כשמבצעים שאילתה לגבי אזורים גדולים יותר, כמו קמפוסים של אוניברסיטאות או מרכזי קניות. - התמקדות ביחידות או באגפים: משתמשים ב-
"structureType": "SECTION"כדי לזהות אגפים בתוך מבנה.
הכתובות צריכות להיות שימושיות
לא לכל המקומות יש כתובות ברורות ברמת הרחוב. המסנן
addressabilityעוזר לכם לשלוט באיכות הכתובות בתוצאות:- דרישה לכתובת ראשית ברורה: כדי להבטיח שלתוצאת היעד הראשית תמיד תהיה כתובת או שם ברמת הרחוב, משתמשים ב-
"addressability": "PRIMARY". האפשרות הזו שימושית למטרות ניווט או תצוגה, שבהן כתובת ברורה היא חיונית. - התרת כתובות ביעדי משנה: במקרים שבהם למקום הראשי אין כתובת, אבל ליחידות בתוכו יש כתובת (למשל, דירות בבניין),
"addressability": "WEAK"מוודא שלפחות למקום הראשי או לאחד מיעדי המשנה שלו יש כתובת. - Any Result: אם נוכחות הכתובת לא רלוונטית לתרחיש השימוש שלכם, השתמשו ב-
"addressability": "ANY". מומלץ מאוד להשתמש באפשרות הזו כשצריך רק מאפיינים גיאומטריים כמו קווי מתאר של מבנים ונקודות ניווט, כי היא משפרת את הדיוק של התוצאות האלה.
דוגמה: סינון לפי בניינים שניתן להציג בהם מודעות
curl -X POST -d '{ "locationQuery": { "location": { "latitude": 37.37348780, "longitude": -122.05678064 }, "placeFilter": { "structureType": "BUILDING", "addressability": "PRIMARY" } }, "languageCode": "en" }' \\ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\ -H "X-Goog-FieldMask: place" \\ https://geocode.googleapis.com/v4/geocode/destinations - בידוד מבנים: אפשר להשתמש ב-