חיפוש בקרבת מקום (חדש) הבקשה מתייחסת לסוג מקום אחד או יותר, ומחזירה רשימה של מקומות תואמים בתוך אזור ספציפי. אנונימיזציה של שדות שמציינת סוג נתונים אחד או יותר הוא שדה חובה. התכונה 'חיפוש בקרבת מקום' (חדש) תומכת רק בבקשות 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
כדי לציין את רשימת השדות שיוחזרו בתשובה, צריך ליצור response field mask. מעבירים את אנונימיזציה של שדות התגובה ל-method באמצעות הפרמטר של כתובת האתר
$fields
אוfields
, או באמצעות כותרת ה-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.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
* השדהplaces.name
מכיל את המקום שם המשאב בפורמט: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.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
כדי לסנן את התוצאות ברשימת הסוגים שמשויכים מקום.כשמציינים סוג ראשי כללי, כמו
"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
נסה בעצמך!
API Explorer מאפשר לכם לשלוח בקשות לדוגמה שתכירו את ה-API ואת האפשרויות של ה-API.
- לוחצים על סמל ה-API,
, בצד שמאל של הדף.
- אפשר להרחיב את הקטע הצגת פרמטרים רגילים ולהגדיר
הפרמטר
fields
ל-field mask. - אפשר לערוך את גוף הבקשה.
- לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים להשתמש לצורך שליחת הבקשה.
בחלונית של API Explorer לוחצים על סמל ההרחבה.
, כדי להרחיב את החלון של API Explorer.