מבוא
בקשה של חיפוש בסביבה (חדש) כוללת סוג אחד או יותר של מקומות, ומחזירה רשימה של מקומות תואמים באזור שצוין. חובה לציין אנונימיזציה של שדה עם סוג נתונים אחד או יותר. חיפוש בסביבה (חדש) תומך רק בבקשות 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
תשובות לחיפוש בסביבה (חדש)
התגובה של חיפוש בסביבה (חדש) היא אובייקט 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: *
מציינים אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את מק"ט חיפוש בסביבה Pro:
places.accessibilityOptions
places.addressComponents
places.addressDescriptor*
places.adrFormatAddress
places.attributions
places.businessStatus
places.consumerAlert
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks
places.googleMapsTypeLabel
places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.id
places.location
places.name**
places.movedPlace
places.movedPlaceId
places.openingDate
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.subDestinations
places.timeZone
places.types
places.utcOffsetMinutes
places.viewport
* תיאורי כתובות זמינים בדרך כלל ללקוחות בהודו, ובמקומות אחרים הם ניסיוניים.
** השדהplaces.nameמכיל את שם המשאב של המקום בפורמט:places/PLACE_ID. אפשר להשתמש ב-places.displayNameכדי לגשת לשם הטקסט של המקום.רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).
השדות הבאים מפעילים את מק"ט חיפוש בסביבה Enterprise:
places.currentOpeningHours
places.currentSecondaryOpeningHours
places.internationalPhoneNumber
places.nationalPhoneNumber
places.priceLevel
places.priceRange
places.rating
places.regularOpeningHours
places.regularSecondaryOpeningHours
places.transitStation
places.userRatingCount
places.websiteUriרשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).
השדות הבאים מפעילים את מק"ט חיפוש בסביבה 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 } }
פרמטרים אופציונליים
-
includeFutureOpeningBusinesses
אם
true, יוחזרו עסקים שצפויים להיפתח בעתיד. ברירת המחדל היאfalse.
כדי לאחזר את הסטטוס של העסק, צריך לכלול אתplaces.businessStatusבמסכת השדות של הבקשה. כדי לאחזר את תאריך הפתיחה הצפוי של העסק, צריך לכלול אתplaces.openingDateבמסכת השדות של הבקשה. -
includedTypes/excludedTypes, includedPrimaryTypes/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
קבלת תיאורים של כתובות
תיאורי כתובות מספקים מידע על המיקום של מקום מסוים, כולל ציוני דרך בסביבה ואזורים שבהם הוא נמצא.
בדוגמה הבאה מוצגת בקשה לחיפוש בסביבה (חדש) של מקומות ליד קניון בסן חוזה. בדוגמה הזו, כוללים את 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" } ] } }, /.../ }
חיפוש עסקים שייפתחו בעתיד
בדוגמה הבאה מוצגת בקשה לחיפוש בסביבה (חדש) של עסקים שייפתחו בעתיד בניו מידוס, איידהו:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
"includeFutureOpeningBusinesses": true,
"maxResultCount": 20,
"locationRestriction": {
"circle": {
"center": {"latitude": 44.9755100, "longitude": -116.2842180},
"radius": 20
}
},
"rankPreference": "DISTANCE"
}' \
"https://places.googleapis.com/v1/places:searchNearby"
התשובה כוללת עסקים שייפתחו בעתיד, יחד עם הסטטוס של העסק ותאריך הפתיחה הצפוי:
{ "places": [ { "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "displayName": { "text": "Roberts Greenhouse and Tree Farm", "languageCode": "en" }, "openingDate": { "year": 2026, "month": 4, "day": 15 } } ] }
קבלת מידע על תחנת תחבורה ציבורית
אפשר להשתמש בחיפוש בסביבה (חדש) כדי לקבל מידע על תחנות של תחבורה ציבורית ברדיוס מסוים ממיקום נתון. גוף התגובה כולל מידע על התחנה, כולל שם התחנה, חברות תחבורה ציבורית שמשתמשות בתחנה וקווים של תחבורה ציבורית שעוברים בתחנה. בנוסף, התשובה כוללת סמל של רכב וצבעים שאפשר להשתמש בהם כדי להציג את המידע על תחנת התחבורה הציבורית.
בדוגמה הבאה מוצגת בקשה לתחנות תחבורה ציבורית ברדיוס של 50 מטר ממרכז מנהטן:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
"includedTypes": ["transit_station"],
"locationRestriction": {
"circle": {
"center": {"latitude": 40.754851, "longitude": -73.984164},
"radius": 50.0
}
}
}' \
"https://places.googleapis.com/v1/places:searchNearby"
גוף התגובה כולל מידע על כל תחנה ברדיוס, על הקווים שעוברים בתחנה, על התראות שפורסמו על ידי רשויות התחבורה הציבורית לגבי התחנה ועל פרטי היציאה:
{ "places": [ { "id": "ChIJH2EstKpZwokRCwZtYyMd5Fg", "displayName": { "text": "6 Av/W 41 St", "languageCode": "en" }, "transitStation": { "displayName": { "text": "6 Av/W 41 St", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "ShortLine Hudson", "languageCode": "en" }, "url": "https://www.coachusa.com/", "lines": [ { "id": "ChIJSQlbzvPwwokRolrIA-Kuh6o", "vehicleType": "BUS", "displayName": { "text": "200 - Northern District – Nanuet", "languageCode": "en" }, "shortDisplayName": { "text": "ShortLine Hudson", "languageCode": "en" }, "textColor": "#000000", "backgroundColor": "#ED60A3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" } } ] }, { "displayName": { "text": "MTA New York City Transit", "languageCode": "en" }, "url": "http://www.mta.info/", "lines": [ { "id": "ChIJjUrj7PBewokR3O3S2JVpBrI", "vehicleType": "SUBWAY", "displayName": { "text": "E Train (8 Av Local)", "languageCode": "en" }, "shortDisplayName": { "text": "E Line", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#0039A6", "url": "https://www.mta.info/schedules/subway/e-train", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/E.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } }, ... ] }, "stops": [ { "id": "ChIJvRnquapZwokRdUOyVwNGbe8", "displayName": { "text": "6 Av/W 41 St", "languageCode": "en" }, "location": { "latitude": 40.754509, "longitude": -73.984216500000016 }, "wheelchairAccessibleEntrance": true } ], "departureBoards": [ { "displayType": "DIRECTION_CENTRIC", "rows": [ { "departures": [ { "timedDeparture": { "scheduledTime": "2026-05-15T22:29:51Z", "timingType": "SCHEDULED" }, "originallyScheduledStopId": "ChIJvRnquapZwokRdUOyVwNGbe8", "lineId": "ChIJA1aFyaZfwokRkO5869M6UXk" } ] }, { "departures": [ { "timedDeparture": { "scheduledTime": "2026-05-15T22:33:55Z", "timingType": "SCHEDULED" }, "originallyScheduledStopId": "ChIJvRnquapZwokRdUOyVwNGbe8", "lineId": "ChIJj3iCEwJfwokRZE2Qtnm4pPI" } ] }, ... ] } ] } }, ... { { "id": "ChIJPyq6TZBZwokRdGoiJ5Iq_hE", "vehicleType": "BUS", "displayName": { "text": "W 44 St - South Ferry", "languageCode": "en" }, "shortDisplayName": { "text": "M55", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#1D59B3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" }, "alerts": [ { "effect": "OTHER", "texts": [ { "headline": { "text": "Information", "languageCode": "en" }, "summary": { "text": "Northbound M20 and M55 stop on State St at Bridge St is closed; use the temporary stop on State St before the intersection instead", "languageCode": "en" }, "fullDescription": { "text": "See a map of the new stop location. What's happening? Construction", "languageCode": "en" } } ], "detailsUrls": [ { "url": "https://www.mta.info/" } ], "cause": "OTHER_CAUSE", "startTime": "2025-04-02T04:00:00Z", "endTime": "2026-06-15T00:00:00Z", "attribution": { "link": { "text": "www.mta.info", "url": "https://www.mta.info/" } }, "createTime": "2026-05-15T22:32:00Z", "severityLevel": "INFO" } ] }, ... } ... }
קבלת מידע על כניסות ונקודות ניווט
אתם יכולים לבקש נקודות כניסה ונקודות ניווט ליעד. הכניסות מגדירות את נקודות הכניסה והיציאה למקום מסוים (לדוגמה, שערים שונים בשדה תעופה או בקניון). נקודות ניווט מגדירות מיקומים בצד הדרך שבהם הניווט צריך להסתיים. זה שימושי להפניית משתמשים לצד הנכון של הכביש או לנקודת הורדה ספציפית.
נקודות ניווט מחזירות navigationPointToken. אפשר להעביר את האסימון הזה אל Navigation SDK (זמין ל-Android או ל-iOS) או אל Routes API כדי להנחות את הנהגים אל המיקום הספציפי הזה. מידע נוסף זמין במאמר Navigation point tokens (אסימונים של נקודות ניווט).
בדוגמה הבאה מוצגת בקשה לחיפוש בסביבה (חדש) שכוללת את entrances ואת navigationPoints במסכת השדות:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
"includedTypes": ["airport"],
"maxResultCount": 1,
"locationRestriction": {
"circle": {
"center": {"latitude": 37.6193, "longitude": -122.3816},
"radius": 1000.0
}
}
}' \
"https://places.googleapis.com/v1/places:searchNearby"
התשובה כוללת את הכניסות ואת נקודות הניווט למקום:
{ "places": [ { "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ", "displayName": { "text": "San Francisco International Airport", "languageCode": "en" }, "entrances": [ { "location": { "latitude": 37.6172154, "longitude": -122.3839724 } }, { "location": { "latitude": 37.6174073, "longitude": -122.384196 } }, ... ], "navigationPoints": [ { "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...", "displayName": { "text": "International Terminal Departures Level", "languageCode": "en" }, "location": { "latitude": 37.6153121, "longitude": -122.3900833 }, "travelModes": ["WALK"] }, { "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...", "displayName": { "text": "Domestic Garage - SFO Short Term Parking", "languageCode": "en" }, "location": { "latitude": 37.6157153, "longitude": -122.3885012 }, "travelModes": ["DRIVE", "WALK"], "usages": ["PARKING"] }, ... ] } ] }
רוצה לנסות?
הכלי APIs Explorer מאפשר לכם לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת האפשרויות שלו.
בצד שמאל של הדף, לוחצים על סמל ה-API api.
אפשר לערוך את פרמטרים של הבקשה.
לוחצים על הכפתור Execute (הפעלה). בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.
בחלונית APIs Explorer, לוחצים על סמל המסך המלא מסך מלא כדי להרחיב את החלון של APIs Explorer.