בקשת Nearby Search (New) מקבלת סוג אחד או יותר של מקום, ומחזירה רשימה של מקומות תואמים באזור שצוין. נדרשת אנונימיזציה של שדות שמציינת סוג נתונים אחד או יותר. התכונה 'חיפוש בקרבת מקום' (חדש) תומכת רק בבקשות POST.
באמצעות API Explorer תוכלו ליצור בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות ה-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 (New) מחזיר אובייקט JSON כתגובה. בתשובה:
- המערך
places
מכיל את כל המקומות התואמים. - כל מקום במערך מיוצג על ידי אובייקט
Place
. האובייקטPlace
מכיל מידע מפורט על מקום יחיד. - השדה FieldMask שמועבר בבקשה מציין את רשימת השדות שמוחזרים באובייקט
Place
.
אובייקט ה-JSON המלא מופיע בתבנית:
{ "places": [ { object (Place) } ] }
פרמטרים נדרשים
-
FieldMask
מציינים את רשימת השדות שיוחזרו בתשובה על ידי יצירת אנונימיזציה של שדות בתשובה. מעבירים את המסכה של שדות התשובה ל-method באמצעות הפרמטר
$fields
אוfields
של כתובת ה-URL, או באמצעות כותרת ה-HTTPX-Goog-FieldMask
. אין רשימת ברירת מחדל של השדות שהוחזרו בתשובה. אם משמיטים את מסיכת השדות, השיטה מחזירה שגיאה.כדאי לבצע אנונימיזציה של שדות כדי לוודא שלא מבקשים נתונים מיותרים, וכך חוסכים זמן עיבוד וחיובים מיותרים.
מציינים רשימה מופרדת בפסיקים של סוגי נתוני המקומות שרוצים להחזיר. לדוגמה, כדי לאחזר את השם המוצג ואת הכתובת של המקום.
X-Goog-FieldMask: places.displayName,places.formattedAddress
אפשר להשתמש ב-
*
כדי לאחזר את כל השדות.X-Goog-FieldMask: *
צריך לציין אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את המק"ט של התכונה 'חיפוש בקרבת מקום' (בסיסי):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.attributions
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.shortFormattedAddress
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
משתמשים ב-places.displayName
כדי לגשת לשם הטקסט של המקום.השדות הבאים מפעילים את המק"ט של התכונה 'חיפוש בקרבת מקום' (מתקדם):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
השדות הבאים מפעילים את המק"ט של התכונה 'חיפוש בקרבת מקום' (מועדף):
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.reviews
,places.reviews
,places.reviews
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 ל-50000.0, כולל. רדיוס ברירת המחדל הוא 0.0. צריך להגדיר אותו בבקשה לערך גדול מ-0.0.
לדוגמה:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
פרמטרים אופציונליים
-
IncludeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
מאפשרת לציין רשימת סוגים של סוגי טבלה א' שמשמשים לסינון תוצאות החיפוש. אפשר לציין עד 50 סוגים בכל קטגוריה של הגבלת סוג.
למקום אפשר לשייך רק סוג ראשי יחיד מהסוגים טבלה א'. לדוגמה, הסוג הראשי יכול להיות
"mexican_restaurant"
או"steak_house"
. אפשר להשתמש ב-includedPrimaryTypes
וב-excludedPrimaryTypes
כדי לסנן את התוצאות לפי הסוג הראשי של מקום.למקום יכולים להיות גם כמה ערכים של סוגים מהסוגים טבלה א' שמשויכים אליו. לדוגמה, מסעדות יכולות להיות מהסוגים הבאים:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. אפשר להשתמש ב-includedTypes
וב-excludedTypes
כדי לסנן את התוצאות ברשימת הסוגים שמשויכים למקום.אם חיפוש מוגדר עם כמה הגבלות סוגים, יוחזרו רק מקומות שעומדים בכל ההגבלות. לדוגמה, אם מציינים את הערך
{"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
רוצה לנסות?
באמצעות API Explorer תוכלו לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת אפשרויות ה-API.
- בצד שמאל של הדף, בוחרים בסמל ה-API .
- אפשר להרחיב את הקטע Show advanced parameters ולהגדיר את הפרמטר
fields
ל-field mask. - אפשר לערוך את גוף הבקשה.
- לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים להשתמש לשליחת הבקשה.
בחלונית של API Explorer, לוחצים על סמל ההרחבה כדי להרחיב את חלון ה-API Explorer.