Una richiesta Ricerca nelle vicinanze (nuova) prende uno o più tipi di luogo e restituisce un elenco di luoghi corrispondenti all'interno dell'area specificata. È richiesta una maschera di campo che specifichi uno o più tipi di dati. La ricerca nelle vicinanze (nuova) supporta solo le richieste POST.
Explorer API ti consente di effettuare richieste in tempo reale in modo da acquisire familiarità con l'API e le relative opzioni:
Prova!Richieste Nearby Search (nuove)
Una richiesta Nearby Search (nuova) è una richiesta POST HTTP a un URL nel modulo:
https://places.googleapis.com/v1/places:searchNearby
Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni come parte della richiesta POST. Ad esempio:
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
Risposte di Nearby Search (nuove)
Nearby Search (New) restituisce un oggetto JSON come risposta. Nella risposta:
- L'array
places
contiene tutte le posizioni corrispondenti. - Ogni posizione nell'array è rappresentata da un oggetto
Place
. L'oggettoPlace
contiene informazioni dettagliate su una singola posizione. - Il valore FieldMask passato nella richiesta specifica l'elenco dei campi
restituiti nell'oggetto
Place
.
L'oggetto JSON completo ha il seguente formato:
{ "places": [ { object (Place) } ] }
Parametri obbligatori
-
FieldMask
Specifica l'elenco dei campi da restituire nella risposta creando una maschera del campo della risposta. Passa la maschera del campo della risposta al metodo utilizzando il parametro URL
$fields
ofields
oppure l'intestazione HTTPX-Goog-FieldMask
. Nella risposta non è presente un elenco predefinito di campi restituiti. Se ometti la maschera del campo, il metodo restituisce un errore.Il mascheramento dei campi è una buona pratica di progettazione per garantire di non richiedere dati non necessari, il che contribuisce a evitare tempi di elaborazione e addebiti di fatturazione superflui.
Specifica un elenco separato da virgole di tipi di dati sui luoghi da restituire. Ad esempio, per recuperare il nome visualizzato e l'indirizzo del luogo.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Utilizza
*
per recuperare tutti i campi.X-Goog-FieldMask: *
Specifica uno o più dei seguenti campi:
I seguenti campi attivano lo SKU di Ricerca nelle vicinanze (di base):
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.subDestinations
,places.adrFormatAddress
,places.adrFormatAddress
,places.adrFormatAddress
,places.adrFormatAddress
,places.adrFormatAddress
,places.adrFormatAddress
,places.adrFormatAddress
,places.adrFormatAddress
places.name
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Utilizzaplaces.displayName
per accedere al nome testuale del luogo.I seguenti campi attivano lo SKU di Ricerca nelle vicinanze (avanzata):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
I seguenti campi attivano lo SKU di Ricerca nelle vicinanze (preferito):
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.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.delivery
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
La regione da cercare specificata come cerchio, definita dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi. Il raggio predefinito è 0,0. Devi impostarlo nella richiesta su un valore maggiore di 0,0.
Ad esempio:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Parametri facoltativi
-
inclusionTypes/excludedTypes, includedprimaryTypes/excludedprimaryTypes
Consente di specificare un elenco di tipi dai tipi utilizzati dalla Tabella A per filtrare i risultati di ricerca. È possibile specificare fino a 50 tipi in ogni categoria di limitazione.
Un luogo può avere un solo singolo tipo principale tra i tipi Tabella A associati. Ad esempio, il tipo principale potrebbe essere
"mexican_restaurant"
o"steak_house"
. UtilizzaincludedPrimaryTypes
eexcludedPrimaryTypes
per filtrare i risultati in base al tipo principale di un luogo.Un luogo può anche avere più valori di tipo dai tipi di Tabella A associati. Ad esempio, un ristorante potrebbe avere i seguenti tipi:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. UtilizzaincludedTypes
eexcludedTypes
per filtrare i risultati nell'elenco dei tipi associati a un luogo.Se una ricerca viene specificata con più limitazioni per i tipi, vengono restituiti solo i luoghi che soddisfano tutte le limitazioni. Ad esempio, se specifichi
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, i luoghi restituiti forniscono servizi correlati a"restaurant"
, ma non operano principalmente come"steak_house"
.includedTypes
Un elenco separato da virgole dei tipi di luoghi da cercare della Tabella A. Se questo parametro viene omesso, vengono restituiti luoghi di tutti i tipi.
excludedTypes
Un elenco separato da virgole di tipi di luoghi della Tabella A da escludere da una ricerca.
Se nella richiesta specifichi sia
includedTypes
( ad esempio"school"
) siaexcludedTypes
(ad esempio"primary_school"
), la risposta include i luoghi classificati come"school"
ma non"primary_school"
. La risposta include i luoghi che corrispondono ad almeno uno diincludedTypes
e a nessuno diexcludedTypes
.Se sono presenti tipi in conflitto, ad esempio un tipo visualizzato in
includedTypes
eexcludedTypes
, viene restituito un erroreINVALID_REQUEST
.includedPrimaryTypes
Un elenco separato da virgole di tipi di luoghi principali della Tabella A da includere in una ricerca.
excludedPrimaryTypes
Un elenco separato da virgole dei tipi di luoghi principali della Tabella A da escludere da una ricerca.
Se sono presenti tipi principali in conflitto, ad esempio un tipo visualizzato in
includedPrimaryTypes
eexcludedPrimaryTypes
, viene restituito un erroreINVALID_ARGUMENT
. -
languageCode
La lingua in cui restituire i risultati.
- Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
- Se
languageCode
non viene fornito, il valore predefinito dell'API saràen
. Se specifichi un codice lingua non valido, l'API restituisce un erroreINVALID_ARGUMENT
. - L'API fa del suo meglio per fornire un indirizzo che sia leggibile sia per l'utente sia per i residenti. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitte in uno script leggibile dall'utente se necessario, osservando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono tutti restituiti nella stessa lingua, che viene scelta dal primo componente.
- Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.
- La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni dei tipi di strada o i sinonimi che possono essere validi in una lingua, ma non in un'altra.
-
maxResultCount
Specifica il numero massimo di risultati relativi a luoghi da restituire. Il valore deve essere compreso tra 1 e 20 (valore predefinito) inclusi.
-
rankPreference
Il tipo di ranking da utilizzare. Se questo parametro viene omesso, i risultati vengono classificati in base alla popolarità. Può essere uno dei seguenti:
POPULARITY
(predefinito) ordina i risultati in base alla loro popolarità.DISTANCE
I risultati vengono ordinati in ordine crescente in base alla distanza dalla posizione specificata.
-
regionCode
Il codice regione utilizzato per formattare la risposta, specificato come valore del codice CLDR a due caratteri. Non è presente alcun valore predefinito.
Se il nome del paese nel campo
formattedAddress
nella risposta corrisponde aregionCode
, il codice paese viene omesso daformattedAddress
. Questo parametro non ha effetto suadrFormatAddress
, che include sempre il nome del paese, o sushortFormattedAddress
, che non lo include mai.La maggior parte dei codici CLDR è identica ai codici ISO 3166-1, con alcune eccezioni importanti. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord"). Il parametro può influire sui risultati in base alla legge vigente.
Esempi di Nearby Search (nuovi)
Trova luoghi di un solo tipo
L'esempio seguente mostra una richiesta Ricerca nelle vicinanze (nuova) per i nomi
visualizzati di tutti i ristoranti entro un raggio di 500 metri, definito da 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
Tieni presente che l'intestazione X-Goog-FieldMask
specifica che la risposta
contiene i seguenti campi di dati: places.displayName
.
La risposta
viene quindi nel modulo:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Aggiungi altri tipi di dati alla maschera del campo per restituire informazioni aggiuntive.
Ad esempio, aggiungi places.formattedAddress,places.types,places.websiteUri
per includere
l'indirizzo del ristorante, il tipo e l'indirizzo web nella risposta:
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
Ora la risposta è nel formato:
{ "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" } }, ... }
Trova luoghi di vari tipi
L'esempio seguente mostra una richiesta Ricerca nelle vicinanze (nuova) per i
nomi visualizzati di tutti i minimarket e i negozi di liquori entro un raggio di 1000 metri dal
circle
specificato:
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:searchNearbyQuesto esempio aggiunge
places.primaryType
e places.types
alla maschera del campo in modo che la risposta includa informazioni sul tipo di ogni luogo, semplificando la selezione del luogo appropriato dai risultati.
Escludere un tipo di luogo dalla ricerca
L'esempio seguente mostra una richiesta di Ricerca nelle vicinanze (nuova) per tutti i luoghi di tipo "school"
, esclusi tutti i luoghi di tipo "primary_school"
, classificando i risultati in base alla distanza:
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
Cerca tutti i luoghi nelle vicinanze di un'area, in base alla distanza
L'esempio seguente mostra una richiesta di ricerca nelle vicinanze (nuova) per luoghi
vicino a un punto nel centro di San Francisco. In questo esempio, includi il parametro rankPreference
per classificare i risultati in base alla distanza:
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
Prova.
Explorer API consente di effettuare richieste di esempio in modo da acquisire familiarità con le opzioni API e API.
- Seleziona l'icona dell'API, , sul lato destro della pagina.
- Se vuoi, espandi Mostra parametri standard e imposta il parametro
fields
sulla maschera di campo. - (Facoltativo) Modifica il Corpo della richiesta.
- Seleziona il pulsante Esegui. Nel popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona di espansione, , per espandere la finestra Explorer API.