מבוא
בבקשה של חיפוש בקרבת מקום (חדש) מציינים סוג אחד או יותר של מקומות, והמערכת מחזירה רשימה של מקומות תואמים באזור שצוין. חובה לציין אנונימיזציה של שדה עם סוג נתונים אחד או יותר. החיפוש בקרבת מקום (חדש) תומך רק בבקשות POST.
APIs Explorer מאפשר לכם לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת האפשרויות שלו:
כדאי לנסות את ההדגמה האינטראקטיבית כדי לראות את התוצאות של 'חיפוש בקרבת מקום' (חדש) שמוצגות במפה.
בקשות של חיפוש בקרבת מקום (חדש)
בקשה לחיפוש בקרבת מקום (חדש) היא בקשת HTTP POST לכתובת URL בפורמט:
https://places.googleapis.com/v1/places:searchNearby
מעבירים את כל הפרמטרים בגוף בקשת ה-JSON או בכותרות כחלק מבקשת ה-POST. לדוגמה:
curl -X POST -d '{
"includedTypes": ["restaurant"],
"maxResultCount": 10,
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby
תשובות בחיפוש בקרבת מקום (חדש)
התגובה של Nearby Search (חדש) היא אובייקט JSON. בתשובה:
- המערך
placesמכיל את כל המקומות התואמים. - כל מקום במערך מיוצג על ידי אובייקט
Place. אובייקטPlaceשמכיל מידע מפורט על מקום יחיד. - השדה FieldMask שמועבר בבקשה מציין את רשימת השדות שמוחזרים באובייקט
Place.
אובייקט ה-JSON המלא הוא מהצורה:
{
"places": [
{
object (Place)
}
]
}פרמטרים נדרשים
-
FieldMask
כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים מסכת שדות של תגובה. מעבירים את מסכת שדות התגובה לשיטה באמצעות פרמטר כתובת ה-URL
$fieldsאוfields, או באמצעות כותרת ה-HTTPX-Goog-FieldMask. אין רשימת ברירת מחדל של שדות שמוחזרים בתגובה. אם לא מציינים את מסכת השדה, השיטה מחזירה שגיאה.הסתרת שדות היא שיטת עיצוב טובה שמבטיחה שלא תבקשו נתונים מיותרים, וכך תוכלו להימנע מזמן עיבוד מיותר ומחיובים מיותרים.
מציינים רשימה מופרדת בפסיקים של סוגי נתונים של מקומות להחזרה. לדוגמה, כדי לאחזר את השם המוצג ואת הכתובת של המקום.
X-Goog-FieldMask: places.displayName,places.formattedAddress
כדי לאחזר את כל השדות, משתמשים ב-
*.X-Goog-FieldMask: *
מציינים אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את מק"ט Nearby Search Pro:
places.accessibilityOptions
places.addressComponents
places.addressDescriptor*
places.adrFormatAddress
places.attributions
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks
places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.id
places.location
places.name**
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
* תיאורי כתובות זמינים לכלל המשתמשים בהודו, ובמקומות אחרים הם זמינים כניסוי.
** השדהplaces.nameמכיל את שם המשאב של המקום בפורמט:places/PLACE_ID. אפשר להשתמש ב-places.displayNameכדי לגשת לשם הטקסט של המקום.השדות הבאים מפעילים את מק"ט Nearby Search Enterprise:
places.currentOpeningHours
places.currentSecondaryOpeningHours
places.internationalPhoneNumber
places.nationalPhoneNumber
places.priceLevel
places.priceRange
places.rating
places.regularOpeningHours
places.regularSecondaryOpeningHours
places.userRatingCount
places.websiteUriהשדות הבאים מפעילים את מק"ט Nearby Search Enterprise + Atmosphere:
places.allowsDogs
places.curbsidePickup
places.delivery
places.dineIn
places.editorialSummary
places.evChargeAmenitySummary
places.evChargeOptions
places.fuelOptions
places.generativeSummary
places.goodForChildren
places.goodForGroups
places.goodForWatchingSports
places.liveMusic
places.menuForChildren
places.neighborhoodSummary
places.parkingOptions
places.paymentOptions
places.outdoorSeating
places.reservable
places.restroom
places.reviews
places.reviewSummary
routingSummaries*
places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
* חיפוש טקסט וחיפוש בקרבת מקום בלבד
-
locationRestriction
האזור לחיפוש, שמוגדר כעיגול עם נקודת מרכז ורדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50,000.0, כולל. רדיוס ברירת המחדל הוא 0.0. צריך להגדיר אותו בבקשה לערך שגדול מ-0.0.
לדוגמה:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
פרמטרים אופציונליים
-
includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes
מאפשר לציין רשימה של סוגים מתוך types טבלה א' שמשמשת לסינון תוצאות החיפוש. אפשר לציין עד 50 סוגים בכל קטגוריה של הגבלת סוג.
לכל מקום יכול להיות סוג ראשי אחד מתוך הסוגים שמפורטים בטבלה א'. לדוגמה, הסוג הראשי יכול להיות
"mexican_restaurant"או"steak_house". אפשר להשתמש ב-includedPrimaryTypesוב-excludedPrimaryTypesכדי לסנן את התוצאות לפי הסוג הראשי של המקום.למקום יכולים להיות משויכים גם כמה ערכי סוג מתוך הסוגים טבלה א'. לדוגמה, מסעדה יכולה להיות מסוגים הבאים:
"seafood_restaurant","restaurant","food","point_of_interest","establishment". כדי לסנן את התוצאות ברשימת הסוגים שמשויכים למקום, משתמשים במקשיםincludedTypesו-excludedTypes.כשמציינים סוג ראשי כללי, כמו
"restaurant"או"hotel", התשובה יכולה להכיל מקומות עם סוג ראשי ספציפי יותר מזה שצוין. לדוגמה, מציינים לכלול סוג ראשי של"restaurant". התשובה יכולה להכיל מקומות עם סוג ראשי של"restaurant", אבל היא יכולה גם להכיל מקומות עם סוג ראשי ספציפי יותר, כמו"chinese_restaurant"או"seafood_restaurant".אם מציינים כמה הגבלות על סוג החיפוש, יוחזרו רק מקומות שעומדים בכל ההגבלות. לדוגמה, אם מציינים
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, המקומות שיוחזרו מספקים שירותים שקשורים ל-"restaurant"אבל לא פועלים בעיקר כ-"steak_house".includedTypes
רשימה מופרדת בפסיקים של סוגי המקומות מטבלה א' לחיפוש. אם לא מציינים את הפרמטר הזה, מוחזרים מקומות מכל הסוגים.
excludedTypes
רשימה של סוגי מקומות מטבלה א' שמופרדים בפסיקים, להחרגה מחיפוש.
אם מציינים בבקשה גם את
includedTypes( לדוגמה,"school") וגם אתexcludedTypes(לדוגמה,"primary_school"), התשובה כוללת מקומות שמסווגים כ-"school"אבל לא כ-"primary_school". התשובה כוללת מקומות שתואמים לפחות לאחד מהערכיםincludedTypesולאף אחד מהערכיםexcludedTypes.אם יש סוגים סותרים, למשל סוג שמופיע גם ב-
includedTypesוגם ב-excludedTypes, הפונקציה מחזירה שגיאתINVALID_REQUEST.includedPrimaryTypes
רשימה מופרדת בפסיקים של סוגי מקומות ראשיים מטבלה א' שרוצים לכלול בחיפוש.
excludedPrimaryTypes
רשימה מופרדת בפסיקים של סוגי מקומות ראשיים מטבלה א' שרוצים להחריג מחיפוש.
אם יש סוגים ראשיים סותרים, למשל אם סוג מסוים מופיע גם ב-
includedPrimaryTypesוגם ב-excludedPrimaryTypes, תוחזר שגיאתINVALID_ARGUMENT. -
languageCode
השפה שבה יוחזרו התוצאות.
- כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
- אם לא מציינים את הערך
languageCode, ברירת המחדל של ה-API היאen. אם מציינים קוד שפה לא תקין, ה-API מחזיר שגיאהINVALID_ARGUMENT. - ה-API עושה כמיטב יכולתו כדי לספק כתובת רחוב שגם המשתמש וגם תושבי המקום יוכלו לקרוא. כדי להשיג את המטרה הזו, היא מחזירה כתובות בשפה המקומית, בתעתיק לכתב שהמשתמש יכול לקרוא אם צריך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מתוך הרכיב הראשון.
- אם שם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שממשק ה-API בוחר להחזיר, ועל הסדר שבו הן מוחזרות. הגיאוקודר מפרש קיצורים באופן שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות, או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת.
-
maxResultCount
מציין את המספר המקסימלי של תוצאות של מקומות שיוחזרו. הערך חייב להיות בין 1 ל-20 (ברירת מחדל), כולל.
-
rankPreference
סוג הדירוג שבו רוצים להשתמש. אם לא מציינים את הפרמטר הזה, התוצאות מדורגות לפי פופולריות. יכול להיות אחת מהאפשרויות הבאות:
-
POPULARITY(ברירת מחדל) מיון התוצאות לפי הפופולריות שלהן. DISTANCEמיון התוצאות בסדר עולה לפי המרחק שלהן מהמיקום שצוין.
-
-
regionCode
קוד האזור שמשמש לעיצוב התשובה, שמוגדר כערך של קוד CLDR בן שני תווים. אין ערך ברירת מחדל.
אם שם המדינה בשדה
formattedAddressבתשובה תואם לערךregionCode, קוד המדינה מושמט מהשדהformattedAddress. לפרמטר הזה אין השפעה עלadrFormatAddress, שתמיד כולל את שם המדינה, או עלshortFormattedAddress, שלעולם לא כולל אותו.רוב הקודים של CLDR זהים לקודי ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא uk (.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.
דוגמאות לחיפוש בקרבת מקום (חדש)
חיפוש מקומות מסוג מסוים
בדוגמה הבאה מוצגת בקשה לחיפוש בקרבת מקום (חדש) של השמות המוצגים של כל המסעדות ברדיוס של 500 מטר, שמוגדר על ידי circle:
curl -X POST -d '{
"includedTypes": ["restaurant"],
"maxResultCount": 10,
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby
שימו לב שהכותרת X-Goog-FieldMask מציינת שהתגובה מכילה את שדות הנתונים הבאים: places.displayName.
התשובה תהיה בפורמט הבא:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
כדי להחזיר מידע נוסף, מוסיפים עוד סוגי נתונים למסכת השדות.
לדוגמה, מוסיפים places.formattedAddress,places.types,places.websiteUri כדי לכלול בתשובה את כתובת המסעדה, הסוג וכתובת האינטרנט:
curl -X POST -d '{
"includedTypes": ["restaurant"],
"maxResultCount": 10,
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby
התשובה מופיעה עכשיו בטופס:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
חיפוש מקומות מכמה סוגים
בדוגמה הבאה מוצגת בקשה לחיפוש בקרבת מקום (חדש) של השמות המוצגים של כל חנויות הנוחות וחנויות המשקאות ברדיוס של 1,000 מטרים מהמיקום circle שצוין:
curl -X POST -d '{
"includedTypes": ["liquor_store", "convenience_store"],
"maxResultCount": 10,
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 1000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
places.primaryType ו-places.types מתווספים למסכת השדות
כדי שהתגובה תכלול מידע על הסוג של כל מקום, וכך יהיה קל יותר לבחור את המקום המתאים מתוך התוצאות.
החרגת סוג מקום מחיפוש
בדוגמה הבאה מוצגת בקשה לחיפוש בסביבה הקרובה (חדש) של כל המקומות
מסוג "school", לא כולל כל המקומות מסוג "primary_school", עם דירוג של התוצאות
לפי מרחק:
curl -X POST -d '{
"includedTypes": ["school"],
"excludedTypes": ["primary_school"],
"maxResultCount": 10,
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 1000.0
}
},
"rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby
חיפוש של כל המקומות בקרבת אזור מסוים, ודירוג לפי מרחק
בדוגמה הבאה מוצגת בקשה לחיפוש בקרבת מקום (חדש) של מקומות ליד נקודה בדאונטאון סן פרנסיסקו. בדוגמה הזו, הפרמטר rankPreference
משמש לדירוג התוצאות לפי מרחק:
curl -X POST -d '{
"maxResultCount": 10,
"rankPreference": "DISTANCE",
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 1000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby
קבלת תיאורים של כתובות
תיאורי כתובות מספקים מידע על המיקום של מקום מסוים, כולל ציוני דרך בסביבה ואזורים שכוללים את המקום.
בדוגמה הבאה מוצגת בקשה לחיפוש בקרבת מקום (חדש) של מקומות ליד קניון בסן חוזה. בדוגמה הזו, כוללים את addressDescriptors
במסכת השדה:
curl -X POST -d '{
"maxResultCount": 5,
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.321328,
"longitude": -121.946275
},"radius": 1000
}
},
"includedTypes": ["restaurant", "cafe"],
"excludedTypes": [],
"rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby
התשובה כוללת את המקום שצוין בבקשה, רשימה של ציוני דרך בסביבה והמרחק שלהם מהמקום, ורשימה של אזורים והקשר שלהם למקום:
{ "places": [ { "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "addressDescriptor": { "landmarks": [ { "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4", "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4", "displayName": { "text": "Nordstrom", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "point_of_interest", "shoe_store", "store" ], "straightLineDistanceMeters": 114.76984, "travelDistanceMeters": 114.261856 }, { "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0", "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0", "displayName": { "text": "Valley Fair Mall Eyexam of CA", "languageCode": "en" }, "types": [ "establishment", "health", "point_of_interest" ], "straightLineDistanceMeters": 131.62566, "travelDistanceMeters": 237.33253 }, { "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "displayName": { "text": "Din Tai Fung", "languageCode": "en" }, "types": [ "establishment", "food", "point_of_interest", "restaurant" ], "straightLineDistanceMeters": 110.0775, "travelDistanceMeters": 171.41951 }, { "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54", "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54", "displayName": { "text": "Abercrombie & Fitch", "languageCode": "en" }, "types": [ "clothing_store", "establishment", "point_of_interest", "shoe_store", "store" ], "spatialRelationship": "DOWN_THE_ROAD", "straightLineDistanceMeters": 53.620117, "travelDistanceMeters": 2.4578214 }, { "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU", "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU", "displayName": { "text": "Hollister Co.", "languageCode": "en" }, "types": [ "clothing_store", "establishment", "point_of_interest", "shoe_store", "store" ], "spatialRelationship": "DOWN_THE_ROAD", "straightLineDistanceMeters": 56.53726, "travelDistanceMeters": 15.418246 } ], "areas": [ { "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "displayName": { "text": "Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM", "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM", "displayName": { "text": "Central San Jose", "languageCode": "en" }, "containment": "OUTSKIRTS" } ] } }, /.../ }
רוצה לנסות?
באמצעות APIs Explorer אפשר לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת האפשרויות שלו.
לוחצים על סמל ה-API api בצד שמאל של הדף.
אפשר לערוך את פרמטרים הבקשה.
לוחצים על הלחצן Execute (הפעלה). בתיבת הדו-שיח, בוחרים את החשבון שרוצים להשתמש בו כדי לשלוח את הבקשה.
בחלונית APIs Explorer, בוחרים בסמל המסך המלא מסך מלא כדי להרחיב את החלון של APIs Explorer.