בקשת חיפוש בקרבת מקום (חדש) מקבלת סוג אחד או יותר של מקומות, ומחזירה רשימה של מקומות תואמים באזור שצוין. נדרשת אנונימיזציה של שדות שמציינת סוג אחד או יותר של נתונים. חיפוש בקרבת מקום (חדש) תומך רק בבקשות 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
תגובות מחיפוש בקרבת מקום (חדש)
התכונה 'חיפוש בקרבת מקום' (חדש) מחזירה אובייקט JSON כתגובה. בתשובה:
- המערך
places
מכיל את כל המקומות התואמים. - כל מקום במערך מיוצג על ידי אובייקט
Place
. האובייקטPlace
מכיל מידע מפורט על מקום אחד. - השדה FieldMask שהועבר בבקשה מציין את רשימת השדות
שהוחזרו באובייקט
Place
.
אובייקט ה-JSON המלא מופיע בצורה הבאה:
{ "places": [ { object (Place) } ] }
פרמטרים נדרשים
-
FieldMask
כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים אנונימיזציה של שדות התשובה. מעבירים את המסכה של שדה התגובה לשיטה באמצעות הפרמטר של כתובת האתר
$fields
אוfields
, או באמצעות כותרת ה-HTTPX-Goog-FieldMask
. אין בתשובה רשימת ברירת מחדל של שדות שהוחזרו. אם משמיטים את מסכת השדות, השיטה מחזירה שגיאה.מומלץ לבצע אנונימיזציה של שדות כדי שלא תבקשו נתונים מיותרים, וכך להימנע מזמן עיבוד ומחיובים מיותרים.
מציינים רשימה מופרדת בפסיקים של סוגי נתוני מקומות שיש להחזיר. לדוגמה, כדי לאחזר את השם המוצג ואת הכתובת של המקום.
X-Goog-FieldMask: places.displayName,places.formattedAddress
כדי לאחזר את כל השדות, צריך להשתמש בפונקציה
*
.X-Goog-FieldMask: *
צריך לציין אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את המק"ט של 'חיפוש בקרבת מקום' (בסיסי):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,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.name
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.liveMusic
places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
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 } }
פרמטרים אופציונליים
-
includedTypes/excludedTypes, includedPrimaryTypes/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 ואת האפשרויות של API.
- לוחצים על סמל ה-API בצד שמאל של הדף.
- אפשר להרחיב את האפשרות הצג פרמטרים סטנדרטיים ולהגדיר את הפרמטר
fields
כאנונימיזציה של שדות. - אפשר לערוך את גוף הבקשה.
- לוחצים על הלחצן ביצוע. בחלון הקופץ, בוחרים את החשבון שבאמצעותו רוצים לשלוח את הבקשה.
בחלונית של API Explorer לוחצים על סמל ההרחבה, , כדי להרחיב את החלון של API Explorer.