Destination הוא נקודת עניין משמעותית או מיקום ספציפי שמשתמש מתכוון להגיע אליו או לנווט אליו. Destination יכול לכלול מידע כמו נקודות ניווט, ציוני דרך, כניסות ומתארים של בניינים.
נקודת הקצה SearchDestinations של Geocoding API מאפשרת לאחזר מידע מפורט על יעדים שונים על סמך קריטריוני קלט שונים, כמו כתובת, מזהה מקום או קואורדינטות של קו רוחב וקו אורך.
בקשה לחיפוש יעדים
בקשה לחיפוש יעדים היא בקשת HTTP POST לכתובת URL בתבנית:
https://geocode.googleapis.com/v4alpha/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/v4alpha/geocode/destinations
יש 3 דרכים לציין את המיקום שממנו רוצים לחפש יעד:
- כתובת
- מזהה מקום
- קואורדינטות של אורך ורוחב
חיפוש יעד לפי כתובת
אפשר לציין את הכתובת כמחרוזת לא מובנית. המרת כתובת לקואורדינטות לא פותרת קואורדינטות של קווי אורך ורוחב, או מחרוזות לא מובנות אחרות שלא מייצגות כתובת או קוד OLC. אין תמיכה בבקשות שמשתמשות במחרוזות כאלה, והן עלולות להוביל לתשובות שגיאה או להתנהגות לא מוגדרת. דוגמאות לשאילתות לא נתמכות:
| סוג השאילתה | דוגמה |
|---|---|
| קואורדינטות של קו רוחב וקו אורך. במקום זאת, צריך להשתמש בשאילתת מיקום. | "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" |
| שאילתות דו-משמעיות עם כמה פרשנויות | "החזרת מטען" |
| שמות היסטוריים שכבר לא נמצאים בשימוש | "Middlesex United Kingdom" |
| רכיבים או כוונות לא גיאוספציאליים | "כמה סירות יש בנמל ונטורה?" |
| שמות לא רשמיים או שמות מותאמים אישית |
"The Jenga" "The Helter Skelter" |
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/v4alpha/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/v4alpha/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/v4alpha/geocode/destinations
חיפוש יעד לפי מיקום
אפשר לחפש יעד באמצעות קואורדינטות של קו אורך וקו רוחב:
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/v4alpha/geocode/destinations
שימוש ב-OAuth כדי לשלוח בקשה
Geocoding API v4 תומך ב-OAuth 2.0 לאימות. כדי להשתמש ב-OAuth עם Geocoding API, צריך להקצות לטוקן OAuth את ההיקף הנכון. Geocoding API תומך בהיקפי ההרשאות הבאים לשימוש עם נקודת הקצה Destinations:
https://www.googleapis.com/auth/maps-platform.geocode— לשימוש עם כל נקודות הקצה של Geocoding API.
בנוסף, אפשר להשתמש בהיקף הכללי https://www.googleapis.com/auth/cloud-platform
לכל נקודות הקצה של Geocoding API. היקף ההרשאות הזה שימושי במהלך הפיתוח, אבל לא בייצור, כי הוא היקף כללי שמאפשר גישה לכל נקודות הקצה.
מידע נוסף ודוגמאות זמינים במאמר בנושא שימוש ב-OAuth.
תגובה של חיפוש יעדים
הקשר למיקום הגיאוגרפי
התשובה של Search Destinations מספקת הקשר עשיר ומקומי מאוד לגבי המיקום. השדות העיקריים כוללים:
-
primary: המקום העיקרי שזוהה על ידי השאילתה בבקשה. -
containingPlaces: ישויות גדולות יותר שהיעד הראשי הוא חלק מהן (לדוגמה, קניון שמכיל חנות). -
subDestinations: מיקומים ספציפיים יותר ביעד הראשי (לדוגמה, דירות בבניין). -
entrances: נקודות כניסה ויציאה ספציפיות ליעד. -
navigationPoints: מיקומים מתאימים ליד כביש לניווט לסיום. -
arrivalSummary: תובנות מבוססות-AI שיעזרו לכם להגיע ליעד. מידע נוסף על סיכומים מבוססי-AI -
landmarks: מקומות בולטים בקרבת מקום כדי לעזור למשתמשים להבין את הסביבה של היעד.
פרטים מלאים על כל שדות התגובה מופיעים בהפניית ה-API.
פורמט התשובה
הפונקציה 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", "american_restaurant", "meal_takeaway", "restaurant", "food_store", "food", "point_of_interest", "store", "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":}, "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.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 ] ] ] }} ], "landmarks":{ ... }
{ "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 ] ] ] }, "entrances": [ { "location": { "latitude": 37.373531299999996, "longitude": -122.05694519999999 }, "tags": [ "PREFERRED" ], "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w" } ], "navigationPoints": [ { "location": { "latitude": 37.3738659, "longitude": -122.05693620000001 }, "travelModes": [ "DRIVE", "WALK" ], "usages": [ "UNKNOWN" ] } ] } ] }[ ... ]
[ { "place": { "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14", "displayName": { "text": "Safeway", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "florist", "butcher_shop", "deli", "bakery", "food_delivery", "supermarket", "market", "food_store", "food", "point_of_interest", "store", "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 } }, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Around the corner from Safeway", "languageCode": "en" }, "straightLineDistanceMeters": 158.65607, "travelDistanceMeters": 131.16699 }, { "place": { "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs", "displayName": { "text": "Starbird Chicken", "languageCode": "en" }, "types": [ "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":}, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Near Starbird Chicken", "languageCode": "en" }, "straightLineDistanceMeters": 87.34801, "travelDistanceMeters": 214.08084 }, { "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 } }, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Near Chase Bank", "languageCode": "en" }, "straightLineDistanceMeters": 61.182194, "travelDistanceMeters": 63.075645 }, { "place": { "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk", "displayName": { "text": "Madras Café", "languageCode": "en" }, "primaryType": "indian_restaurant", "types": [ "indian_restaurant", "coffee_shop", "cafe", "restaurant", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1026", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1177 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3743, "longitude": -122.0549333 } }, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Near Madras Café", "languageCode": "en" }, "straightLineDistanceMeters": 204.45102, "travelDistanceMeters": 235.12041 } ]{ ... }
{ "type": "Polygon", "coordinates": [ [ [ -122.057003840785, 37.3747648209809 ], [ -122.057136852459, 37.3747919153144 ], [ -122.057205005705, 37.3745815131859 ], [ -122.057071994114, 37.3745544186944 ], [ -122.057003840785, 37.3747648209809 ] ] ] }
פרמטרים נדרשים
- אחת מ-3 האפשרויות הבאות צריכה להופיע בבקשת ה-API, כדי לציין את הכתובת, המקום או המיקום שרוצים לחפש בהם יעד:
-
addressQuery– הכתובת לחיפוש. -
place– מזהה המקום של המקום שרוצים לחפש. -
locationQuery– קואורדינטות קו הרוחב וקו האורך של המיקום שרוצים לחפש.
-
FieldMask
כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים מסכת שדות של תגובה. מעבירים את מסכת שדות התגובה לשיטה באמצעות פרמטר כתובת ה-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/v4alpha/geocode/destinationsאין רשימת ברירת מחדל של שדות שמוחזרים בתגובה. אם לא מציינים את מסכת השדה, השיטה מחזירה שגיאה. מגדירים את מסכת השדות ל-
*כדי להחזיר את כל השדות. פרטים נוספים מופיעים במאמר בנושא בחירת שדות להחזרה.
פרמטרים אופציונליים
-
travelModes
מציינת אילו סוגים של
navigationPointsלהחזיר. המערכת תסנן נקודות ניווט של אמצעי תחבורה אחרים. אםtravelModesלא מוגדר, אפשר להחזיר נקודות ניווט של כל אמצעי התחבורה. languageCode
השפה שבה יוחזרו התוצאות.
- כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
-
אם לא מציינים את הערך
languageCode, ברירת המחדל של ה-API היאen. אם מציינים קוד שפה לא תקין, ה-API מחזיר שגיאהINVALID_ARGUMENT. - ה-API עושה כמיטב יכולתו כדי לספק כתובת רחוב שניתן לקרוא אותה גם על ידי המשתמש וגם על ידי תושבים מקומיים. כדי להשיג את המטרה הזו, היא מחזירה כתובות רחוב בשפה המקומית, בתעתיק לכתב שניתן לקריאה על ידי המשתמש אם יש צורך בכך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מתוך הרכיב הראשון.
- אם שם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הכי קרובה.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שממשק ה-API בוחר להחזיר, ועל הסדר שבו התוצאות מוחזרות. הגיאוקודר מפרש קיצורים בצורה שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת.
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/v4alpha/geocode/destinations - בידוד בניינים: אפשר להשתמש ב-
משוב
זוהי נקודת קצה ניסיונית של Geocoding API. נשמח לקבל משוב בכתובת geocoding-feedback-channel@google.com.