Destination הוא נקודת עניין משמעותית או מיקום ספציפי שמשתמש מתכוון להגיע אליו או לנווט אליו. Destination יכול לכלול מידע כמו נקודות ניווט, אתרים ידועים, כניסות ומתארים של בניינים.
נקודת הקצה SearchDestinations של Geocoding API מאפשרת לאחזר מידע מפורט על יעדים שונים על סמך קריטריוני קלט שונים, כמו כתובת, מזהה מקום או קואורדינטות של קו רוחב וקו אורך.
בקשה לחיפוש יעדים
בקשה לחיפוש יעדים היא בקשת HTTP POST לכתובת URL בתבנית:
https://geocode.googleapis.com/v4beta/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/v4beta/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" |
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/v4beta/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/v4beta/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/v4beta/geocode/destinations
מזהי מקומות נתמכים
נקודת הקצה Search Destinations (יעדי חיפוש) פועלת בצורה הטובה ביותר עם מזהי מקומות שמייצגים יעדים ספציפיים שאפשר להגיע אליהם.
בדרך כלל יש תמיכה במזהי מקומות מסוגים כמו establishment, point_of_interest, premise, street_address ו-subpremise.
אין תמיכה במזהי מקומות שלא מייצגים מיקומים נפרדים, כמו מזהים שנובעים מטווחים של כתובות (לדוגמה, '10-20 Main St'), מקטעים של מסלול ללא מספר ספציפי או קודי פלוס.
כדי לוודא את התאימות כשמשתמשים בהשלמה אוטומטית של מקומות כדי למצוא מזהי מקומות,
כדאי לסנן את התוצאות לפי סוג. אפשר להשתמש בפרמטר includedPrimaryTypes בבקשות להשלמה אוטומטית כדי לכלול רק את הסוגים הנתמכים שמפורטים למעלה:
"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]
כך תוכלו לוודא שמזהי המקומות שמוחזרים על ידי ההשלמה האוטומטית של מקומות הם הכי תואמים לשיטה Search Destinations. חשוב לדעת שהסוג establishment הוא רחב. המסנן הזה נחוץ כדי ללכוד הרבה מיקומים של עסקים, אבל הוא עשוי לכלול גם תוצאות של השלמה אוטומטית של מקומות מסוג natural_feature, שיש להם תמיכה מוגבלת בלבד ביעדי חיפוש.
חיפוש יעד לפי מיקום
אפשר לחפש יעדים עם קואורדינטות של קו אורך וקו רוחב:
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/v4beta/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/v4beta/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) או המרה של מקום לקואורדינטות (place 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/v4beta/geocode/destinations - בידוד בניינים: אפשר להשתמש ב-
משוב
זוהי נקודת קצה ניסיונית של Geocoding API. נשמח לקבל משוב בכתובת geocoding-feedback-channel@google.com.