Una Ricerca nelle vicinanze (novità) accetta uno o più tipi di luogo e restituisce un elenco di luoghi corrispondenti all'interno specifica. Una maschera di campo che specifica uno o più tipi di dati è obbligatorio. Ricerca nelle vicinanze (nuova) supporta solo richieste POST.
Explorer API ti consente di effettuare richieste in tempo reale per familiarizzare con l'API e Opzioni API:
Prova!Prova la modalità interattiva demo per visualizzare i risultati di Nearby Search (nuova) su una mappa.
Richieste di Ricerca nelle vicinanze (nuova)
Una richiesta Nearby Search (nuova) è una richiesta POST HTTP a un URL nella modulo:
https://places.googleapis.com/v1/places:searchNearby
Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni come parte del 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)
La funzione Ricerca nelle vicinanze (nuova) restituisce un come risposta. Nella risposta:
- L'array
places
contiene tutti i luoghi corrispondenti. - Ogni punto dell'array è rappresentato da un
Place
. L'oggettoPlace
contiene informazioni dettagliate su un singolo posto. - La FieldMask passata nella richiesta specifica l'elenco dei campi.
restituito 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 un maschera del campo di risposta. Passa la maschera del campo di risposta al metodo utilizzando il parametro URL
$fields
ofields
oppure tramite l'intestazione HTTPX-Goog-FieldMask
. La risposta non contiene un elenco predefinito dei campi restituiti. Se ometti la maschera di campo, il metodo restituisce un errore.Il mascheramento dei campi è una buona pratica di progettazione per garantire di dati non necessari, così da evitare tempi di elaborazione non necessari addebiti di fatturazione.
Specifica un elenco separato da virgole dei tipi di dati dei 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 Nearby Search (Basic):
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
* Il campoplaces.name
contiene il luogo nome risorsa nel formato:places/PLACE_ID
. Usaplaces.displayName
per accedere al nome testuale del luogo.I seguenti campi attivano lo SKU Nearby Search (Advanced):
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 Nearby Search (Preferred):
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
La regione da cercare specificata sotto forma di 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 e 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
-
InclusoType/excludedTypes, IncludeMainTypes/excludedprimaryTypes
Consente di specificare un elenco di tipi da Tabella A utilizzata per filtrare nei risultati di ricerca. È possibile specificare fino a 50 tipi per ogni categoria di limitazione dei tipi.
Un luogo può avere un solo singolo tipo principale tra i tipi Tabella A associata a li annotino. Ad esempio, il tipo principale potrebbe essere
"mexican_restaurant"
o"steak_house"
. Utilizza le funzionalità diincludedPrimaryTypes
eexcludedPrimaryTypes
per filtrare i risultati in base a il tipo principale di un luogo.Un luogo può anche avere più valori di tipo di tipi Tabella A associate. Ad esempio, un ristorante potrebbe avere i seguenti tipi:
"seafood_restaurant"
,"restaurant"
,"food"
"point_of_interest"
"establishment"
. UsaincludedTypes
eexcludedTypes
per filtrare i risultati nell'elenco dei tipi associati a un luogo.Se specifichi un tipo principale generale, ad esempio
"restaurant"
o"hotel"
, la risposta può contenere luoghi con un tipo principale più specifico rispetto a quello specificato. Ad esempio, specifichi di includere un tipo primario di"restaurant"
. La risposta può quindi contenere luoghi con un tipo principale"restaurant"
, ma la risposta può anche contenere luoghi con un indirizzo di tipo principale, come"chinese_restaurant"
o"seafood_restaurant"
.Se una ricerca viene specificata con più limitazioni di tipo, solo luoghi che soddisfano tutte le restrizioni. Ad esempio, se specifichi
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, i luoghi restituiti offrono servizi correlati a"restaurant"
ma non operano principalmente come"steak_house"
.includedTypes
Un elenco separato da virgole dei tipi di luoghi da cercare nella Tabella A. Se questo parametro viene omesso, vengono restituiti luoghi di tutti i tipi.
excludedTypes
Un elenco separato da virgole dei tipi di luogo dalla Tabella A da escludere da una eseguire una ricerca.
Se specifichi sia
includedTypes
( ad esempio"school"
) siaexcludedTypes
(ad es."primary_school"
) nella richiesta, quindi la la risposta include luoghi classificati come"school"
ma non come"primary_school"
. La risposta include i luoghi che corrispondono ad almeno uno diincludedTypes
e nessuno deiexcludedTypes
.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 dei tipi di luoghi principali dalla Tabella A da includere in una ricerca.
excludedPrimaryTypes
Un elenco separato da virgole dei tipi di luoghi principali dalla Tabella A da escludere da una ricerca.
Se sono presenti tipi principali in conflitto, ad esempio un tipo che compare in
includedPrimaryTypes
eexcludedPrimaryTypes
, Viene restituito l'erroreINVALID_ARGUMENT
. -
languageCode
La lingua in cui restituire i risultati.
- Consulta l'elenco delle lingue supportate. spesso su Google aggiorna le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
- Se
languageCode
non viene fornito, l'API predefinita saràen
. Se specifichi un codice lingua non valido, l'API restituisce unINVALID_ARGUMENT
. - L'API fa del suo meglio per fornire una via che sia leggibile sia per l'utente che per locali. Per raggiungere l'obiettivo, restituisce gli indirizzi nella lingua locale, traslitterato in uno script leggibile dall'utente se necessario, osservando lo script preferito lingua. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo 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ù simile.
- La lingua preferita ha una piccola influenza sull'insieme di risultati scelto dall'API da restituire e l'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 ai 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 popolarità.DISTANCE
Ordina i risultati in ordine crescente in base alla loro distanza dal località specificata.
-
regionCode
Il codice regione utilizzato per formattare la risposta, specificato come codice CLDR a due caratteri. Non esiste un valore predefinito.
Se il nome del paese nel campo
formattedAddress
nella risposta corrisponde alregionCode
, il codice paese è omesso daformattedAddress
. Questo parametro non ha effetto sul valoreadrFormatAddress
, che include sempre il paese oppure sushortFormattedAddress
, che non lo include mai.La maggior parte dei codici CLDR è identica a i codici ISO 3166-1 con alcune degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk) mentre il codice ISO 3166-1 è "gb" (tecnicamente per persona giuridica del "Regno Unito di Gran Bretagna e Irlanda del Nord"). Il parametro può influire sui risultati in base alla legge vigente.
Esempi di Ricerca nelle vicinanze (nuova)
Trova luoghi di un tipo
L'esempio seguente mostra una richiesta di Nearby Search (nuova) per la visualizzazione
nomi 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
ha quindi la seguente forma:
{ "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 il parametro
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
La risposta è ora 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 di Nearby Search (nuova) per
visualizzare i nomi di tutti i minimarket e negozi di liquori entro un raggio di 1000 metri dalla
specificato 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:searchNearbyIn questo esempio vengono aggiunti
places.primaryType
e places.types
alla maschera del campo
in modo che la risposta includa informazioni sul tipo di carattere per ogni luogo, semplificando la selezione del
posto appropriato dai risultati.
Escludere un tipo di luogo da una ricerca
L'esempio seguente mostra una richiesta di Ricerca nelle vicinanze (nuova) per tutti i luoghi
di tipo "school"
, escludendo tutti i luoghi di tipo "primary_school"
, classifica i risultati
per 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, classificandoli 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 valore 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 ti consente di effettuare richieste di esempio di acquisire familiarità con le opzioni dell'API e delle API.
- Seleziona l'icona dell'API
. sul lato destro della pagina.
- Se vuoi, espandi Mostra parametri standard e imposta
il parametro
fields
alla maschera del campo. - Se vuoi, modifica il corpo della richiesta.
- Seleziona il pulsante Esegui. Nella finestra popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona Espandi,
, per espandere la finestra Explorer API.