Introduzione
Ricerca testuale (Nuovo) restituisce informazioni su un insieme di luoghi in base a una stringa (ad esempio "pizza a New York", "negozi di scarpe vicino a Ottawa" o "123 Main Street"). Il servizio risponde con un elenco di luoghi corrispondenti alla stringa di testo e all'eventuale bias di località impostato.
Oltre ai parametri obbligatori, Ricerca testuale (nuova) supporta il perfezionamento delle query utilizzando parametri facoltativi per ottenere risultati migliori.
Explorer API ti consente di effettuare richieste in tempo reale per acquisire familiarità con l'API e le relative opzioni:
Richieste di Ricerca testuale (New)
Una richiesta Text Search (New) è una richiesta HTTP POST nel seguente formato:
https://places.googleapis.com/v1/places:searchText
Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni nell'ambito della richiesta POST. Ad esempio:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'Risposte di Ricerca testuale (Nuova)
Ricerca testuale (Nuova) restituisce un oggetto JSON come risposta. Nella risposta:
- L'array
placescontiene tutti i luoghi corrispondenti. - Ogni luogo nell'array è rappresentato da un oggetto
Place. L'oggettoPlacecontiene informazioni dettagliate su un singolo luogo. - Il FieldMask passato nella richiesta specifica l'elenco di campi restituiti nell'oggetto
Place. - Non è garantito che l'elenco di luoghi restituito sia coerente per richieste identiche.
L'oggetto JSON completo ha il seguente formato:
{
"places": [
{
object (Place)
}
]
}Parametri obbligatori
-
FieldMask
Specifica l'elenco di campi da restituire nella risposta creando una maschera di campi di risposta. Passa la maschera di campo della risposta al metodo utilizzando il parametro URL
$fieldsofieldsoppure l'intestazione HTTPX-Goog-FieldMask. Non esiste un elenco predefinito di campi restituiti nella risposta. Se ometti la maschera di campo, il metodo restituisce un errore.Il mascheramento dei campi è una buona pratica di progettazione per garantire che non vengano richiesti dati non necessari, il che aiuta a evitare tempi di elaborazione e addebiti di fatturazione non necessari.
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 Ricerca testuale Essentials ID Only:
places.attributions
places.id
places.consumerAlert
places.name*
nextPageToken
places.movedPlace
places.movedPlaceId* Il campo
places.namecontiene il nome della risorsa del luogo nel formato:places/PLACE_ID. Utilizzaplaces.displayNamenello SKU Pro per accedere al nome di testo del luogo.Per un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (novità).
I seguenti campi attivano lo SKU Ricerca testuale Pro:
places.accessibilityOptions
places.addressComponents
places.addressDescriptor*
places.adrFormatAddress
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks
places.googleMapsTypeLabel
places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.location
places.openingDate
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.searchUri
places.subDestinations
places.timeZone
places.types
places.utcOffsetMinutes
places.viewport
* I descrittori di indirizzo sono generalmente disponibili per i clienti in India e sono sperimentali altrove.Per un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (novità).
I seguenti campi attivano lo SKU Ricerca testuale Enterprise:
places.currentOpeningHours
places.currentSecondaryOpeningHours
places.internationalPhoneNumber
places.nationalPhoneNumber
places.priceLevel
places.priceRange
places.rating
places.regularOpeningHours
places.regularSecondaryOpeningHours
places.transitStation
places.userRatingCount
places.websiteUriPer un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (novità).
I seguenti campi attivano lo SKU Ricerca testuale 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
* Solo Ricerca testuale e Nearby SearchPer un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (novità).
-
textQuery
La stringa di testo in cui cercare. Ad esempio, "ristorante", "123 Main Street" o "Miglior luogo da visitare a San Francisco". L'API restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base alla loro pertinenza percepita.
La Ricerca testuale (nuova) non è destinata a query ambigue, tra cui:
Tipo di query Esempio Troppi concetti o vincoli, ad esempio i nomi di più luoghi, strade o città in una singola query "Market Street San Francisco San Jose Airport" Elementi dell'indirizzo postale non rappresentati su Google Maps "C/O Mario Rossi 123 Main Street"
"Casella postale 13 San Francisco"Nomi di attività, catene o categorie combinati con località in cui queste entità non sono disponibili "Tesco vicino a Dallas, Texas" Query ambigue con più interpretazioni "Consegna del caricabatterie" Nomi storici non più in uso "Middlesex United Kingdom" Elementi o intenti non geospaziali "Quante barche ci sono nel porto di Ventura?" Nomi non ufficiali o vanity "The Jenga"
"The Helter Skelter"Coordinate di latitudine e longitudine "37.422131,-122.084801"
Parametri facoltativi
-
includeFutureOpeningBusinesses
Se
true, restituisce le attività che dovrebbero aprire in futuro. Il valore predefinito èfalse.
Per recuperare lo stato dell'attività, includiplaces.businessStatusnella maschera di campo della richiesta. Per recuperare la data di apertura prevista dell'attività, includiplaces.openingDatenella maschera dei campi della richiesta. -
includedType
Influenza i risultati in base ai luoghi corrispondenti al tipo specificato definito dalla Tabella A. Puoi specificare un solo tipo. Ad esempio:
"includedType":"bar""includedType":"pharmacy"
Ricerca testuale (Nuova) applica il filtro per tipo per alcune query, a seconda dell'applicabilità. Ad esempio, il filtro per tipo potrebbe non essere applicato alle query per indirizzi specifici ("123 Main Street"), ma viene quasi sempre applicato alle query per categorie ("negozi nelle vicinanze" o "centri commerciali").
Per applicare il filtro per tipo a tutte le query, imposta
strictTypeFilteringsutrue. -
includePureServiceAreaBusinesses
Se impostato su
true, la risposta include le attività che visitano o consegnano direttamente ai clienti, ma non hanno una sede fisica. Se impostata sufalse, l'API restituisce solo le attività con una sede fisica. 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
languageCodenon viene fornito, l'API utilizza il valore predefinitoen. Se specifichi un codice lingua non valido, l'API restituisce un erroreINVALID_ARGUMENT. - L'API fa del suo meglio per fornire un indirizzo leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un alfabeto leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti 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 per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra.
locationBias
Specifica un'area in cui eseguire la ricerca. Questa località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata.
Puoi specificare
locationRestrictionolocationBias, ma non entrambi. Pensa alocationRestrictioncome alla regione in cui devono trovarsi i risultati e alocationBiascome alla regione in cui i risultati si troveranno probabilmente o vicino alla quale si troveranno, ma che possono essere al di fuori dell'area.Specifica la regione come area visibile rettangolare o come cerchio.
Un cerchio è definito 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. Ad esempio:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due punti basso e alto diagonalmente opposti. Il punto più basso indica l'angolo sud-ovest del rettangolo, mentre il punto più alto rappresenta l'angolo nord-est del rettangolo.
Un'area visibile è considerata una regione chiusa, il che significa che include il suo confine. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi, mentre i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi:
- Se
low=high, l'area visibile è costituita da quel singolo punto. - Se
low.longitude>high.longitude, l'intervallo di longitudine viene invertito (l'area visibile attraversa la linea di longitudine di 180 gradi). - Se
low.longitude= -180 gradi ehigh.longitude= 180 gradi, l'area visibile include tutte le longitudini. - Se
low.longitude= 180 gradi ehigh.longitude= -180 gradi, l'intervallo di longitudine è vuoto. - Se
low.latitude>high.latitude, l'intervallo di latitudine è vuoto.
Sia il valore di base che il valore finale devono essere compilati e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.
Ad esempio, questa area visibile racchiude completamente New York City:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Se
locationRestriction
Specifica un'area in cui cercare solo query di categoria, che possono restituire più luoghi (ad esempio, "Ristoranti a New York" o "Centri commerciali"). I risultati al di fuori dell'area specificata non vengono restituiti.
Specifica la regione come area visibile rettangolare. Per un esempio di definizione dell'area visibile, consulta la descrizione di
locationBias.Puoi specificare
locationRestrictionolocationBias, ma non entrambi. Pensa alocationRestrictioncome alla regione in cui devono trovarsi i risultati e alocationBiascome alla regione in cui i risultati si troveranno probabilmente o vicino alla quale si troveranno, ma che possono essere al di fuori dell'area.evOptions
Specifica i parametri per identificare i connettori di ricarica per veicoli elettrici (EV) disponibili e le tariffe di ricarica.
connectorTypes
Filtra in base al tipo di connettore di ricarica EV disponibile in un luogo. Un luogo che non supporta nessuno dei tipi di connettore verrà filtrato. I tipi di connettori di ricarica per EV supportati includono caricabatterie combinati (CA e CC), caricabatterie Tesla, caricabatterie conformi a GB/T (per la ricarica rapida di EV in Cina) e caricabatterie con presa a muro. Per saperne di più, consulta la documentazione di riferimento.
- Per filtrare i risultati per un connettore supportato specifico, imposta
connectorTypessu quel valore. Ad esempio, per trovare i connettori di tipo 1 J1772, impostaconnectorTypessuEV_CONNECTOR_TYPE_J1772. - Per filtrare i risultati per i connettori non supportati, imposta
connectorTypessuEV_CONNECTOR_TYPE_OTHER. - Per filtrare i risultati per qualsiasi tipo di connettore che sia una presa a muro, imposta
connectorTypessuEV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET. - Per filtrare i risultati per qualsiasi tipo di connettore, imposta
connectorTypessuEV_CONNECTOR_TYPE_UNSPECIFIEDo non impostare un valore perconnectorTypes.
- Per filtrare i risultati per un connettore supportato specifico, imposta
minimumChargingRateKw
Filtra i luoghi in base alla velocità di ricarica minima dei caricabatterie EV in kilowatt (kW). Tutti i luoghi con una velocità di ricarica inferiore alla velocità di ricarica minima vengono filtrati. Ad esempio, per trovare caricabatterie EV con velocità di ricarica di almeno 10 kW, puoi impostare questo parametro su "10".
minRating
Limita i risultati solo a quelli la cui valutazione media degli utenti è maggiore o uguale a questo limite. I valori devono essere compresi tra 0,0 e 5,0 (inclusi) con incrementi di 0,5. Ad esempio: 0, 0,5, 1,0, … , 5,0 inclusi. I valori vengono arrotondati per eccesso allo 0,5 più vicino. Ad esempio, un valore di 0,6 elimina tutti i risultati con una valutazione inferiore a 1,0.
openNow
Se
true, restituisce solo i luoghi aperti al momento dell'invio della query. Sefalse, restituisci tutte le attività, indipendentemente dallo stato di apertura. I luoghi che non specificano l'orario di apertura nel database di Google Places vengono restituiti se imposti questo parametro sufalse.pageSize
Specifica il numero di risultati, compreso tra 1 e 20, da visualizzare in ogni pagina. Ad esempio, se imposti un valore
pageSizepari a 5, vengono restituiti fino a 5 risultati nella prima pagina. Se la query può restituire più risultati, la risposta include unnextPageTokenche puoi passare in una richiesta successiva per accedere alla pagina successiva.Questo campo sostituisce il campo
maxResultCountdeprecato. Se specifichi siapageSizechemaxResultCount, l'API utilizzapageSizee ignoramaxResultCount.pageToken
Specifica il
nextPageTokendal corpo della risposta della pagina precedente.-
priceLevels
Limita la ricerca ai luoghi contrassegnati con determinati livelli di prezzo. Per impostazione predefinita, vengono selezionati tutti i livelli di prezzo.
I livelli di prezzo possono essere previsti per i luoghi dei seguenti tipi:
I luoghi di tipi non supportati non verranno inclusi nella risposta se viene specificato
priceLevels.Specifica un array di uno o più valori definiti da
PriceLevel.Ad esempio:
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
rankPreference
Specifica il ranking dei risultati nella risposta in base al tipo di query:
- Per una query di categoria come "Ristoranti a New York",
RELEVANCE(classifica i risultati in base alla pertinenza della ricerca) è l'impostazione predefinita. Puoi impostarerankPreferencesuRELEVANCEoDISTANCE(classifica i risultati in base alla distanza). - Per una query non di categoria come "Mountain View, CA", ti consigliamo di lasciare
rankPreferencenon impostato.
- Per una query di categoria come "Ristoranti a New York",
regionCode
Il codice regione utilizzato per formattare la risposta, specificato come valore del codice CLDR di due caratteri. Questo parametro può anche avere un effetto di bias sui risultati di ricerca. Non esiste un valore predefinito.
Se il nome del paese del campo
formattedAddressnella risposta corrisponde aregionCode, il codice paese viene omesso daformattedAddress. Questo parametro non ha alcun effetto suadrFormatAddress, che include sempre il nome del paese, se disponibile, o sushortFormattedAddress, che non lo include mai.La maggior parte dei codici CLDR è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il suo 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.
strictTypeFiltering
Utilizzato con il parametro
includedType. Se impostato sutrue, vengono restituiti solo i luoghi che corrispondono ai tipi specificati daincludedType. Se false, il valore predefinito, la risposta può contenere luoghi che non corrispondono ai tipi specificati.
Esempi di Ricerca testuale (New)
Trova un luogo tramite una stringa di query
L'esempio seguente mostra una richiesta di Ricerca testuale (nuova) per "Cibo vegetariano piccante a Sydney, Australia":
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
Tieni presente che l'intestazione X-Goog-FieldMask specifica che la risposta contiene i seguenti campi di dati: places.displayName,places.formattedAddress.
La risposta è nel formato:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, ... ] }
Aggiungi altri tipi di dati alla maschera di campo per restituire ulteriori informazioni.
Ad esempio, aggiungi places.types,places.websiteUri per includere il tipo di ristorante e l'indirizzo web nella risposta:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-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:searchText'La risposta è ora nel formato:
{ "places": [ { "types": [ "vegetarian_restaurant", "vegan_restaurant", "chinese_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "websiteUri": "http://www.motherchusvegetarian.com.au/", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "types": [ "vegan_restaurant", "thai_restaurant", "vegetarian_restaurant", "indian_restaurant", "italian_restaurant", "american_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "websiteUri": "http://www.veggosizzle.com.au/", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, ... ] }
Filtra i luoghi per livello di prezzo
Utilizza l'opzione priceLevel per filtrare i risultati in base ai ristoranti definiti economici o moderatamente costosi:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'Questo esempio utilizza anche l'intestazione X-Goog-FieldMask per aggiungere il campo di dati places.priceLevel alla risposta, in modo che sia nel formato:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "115 King St, Newtown NSW 2042, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Green Mushroom", "languageCode": "en" } }, ... ] }
Aggiungi altre opzioni per perfezionare la ricerca, ad esempio includedType,
minRating, rankPreference, openNow
e altri parametri descritti in
Parametri facoltativi.
Limita la ricerca a un'area specifica
Utilizza locationRestriction o locationBias, ma non entrambi, per limitare una ricerca a un'area. Pensa a locationRestriction come alla regione in cui devono trovarsi i risultati e a locationBias come alla regione a cui i risultati devono essere vicini, ma possono trovarsi al di fuori dell'area.
Limita l'area utilizzando locationRestriction
Utilizza il parametro locationRestriction per limitare i risultati della query a una regione specificata. Nel corpo della richiesta, specifica i valori di latitudine e longitudine low e high che definiscono il confine della regione.
L'esempio seguente mostra una richiesta di Ricerca testuale (nuova) per "cibo vegetariano" a New York. Questa richiesta restituisce solo i primi 10 risultati per i luoghi aperti.
curl -X POST -d '{
"textQuery" : "vegetarian food",
"pageSize" : "10",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 40.477398,
"longitude": -74.259087
},
"high": {
"latitude": 40.91618,
"longitude": -73.70018
}
}
}
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
Personalizza i risultati in base a un'area utilizzando locationBias
L'esempio seguente mostra una richiesta di Ricerca testuale (nuova) per "cibo vegetariano" con bias di località entro 500 metri da un punto nel centro di San Francisco. Questa richiesta restituisce solo i primi 10 risultati per i luoghi aperti.
curl -X POST -d '{
"textQuery" : "vegetarian food",
"openNow": true,
"pageSize": 10,
"locationBias": {
"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' \
'https://places.googleapis.com/v1/places:searchText'
Cerca caricabatterie EV con una velocità di ricarica minima
Utilizza minimumChargingRateKw e connectorTypes per cercare luoghi con caricabatterie disponibili compatibili con il tuo EV.
L'esempio seguente mostra una richiesta di connettori di ricarica EV di tipo Tesla e J1772 tipo 1 con una velocità di ricarica minima di 10 kW a Mountain View, in California. Vengono restituiti solo quattro risultati.
curl -X POST -d '{
"textQuery": "EV Charging Station Mountain View",
"pageSize": 4,
"evOptions": {
"minimumChargingRateKw": 10,
"connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
}
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'
La richiesta restituisce la seguente risposta:
{ "places": [ { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 16, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 100, "count": 8, "availableCount": 5, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 2, "availableCount": 2, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, ... ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 6, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 4, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 2, "availableCount": 0, "outOfServiceCount": 2, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, ... ] }
Cerca attività al domicilio del cliente
Utilizza il parametro includePureServiceAreaBusinesses per cercare attività senza un indirizzo fisico (ad esempio, un servizio di pulizia mobile o un furgone ristorante).
L'esempio seguente mostra una richiesta di idraulici a San Francisco:
curl -X POST -d '{
"textQuery" : "plumber San Francisco",
"includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
Nella risposta, le attività senza un indirizzo di servizio fisico non includono il campo formattedAddress:
{ "places": [ { "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA", "displayName": { "text": "Advanced Plumbing & Drain", "languageCode": "en" } }, { "displayName": { "text": "Starboy Plumbing Inc.", "languageCode": "en" } }, ... ] }
Specifica il numero di risultati da restituire per pagina
Utilizza il parametro pageSize per specificare un numero di risultati da restituire per pagina. Il parametro nextPageToken nel corpo della risposta fornisce un token che può essere utilizzato nelle chiamate successive per accedere alla pagina successiva dei risultati.
L'esempio seguente mostra una richiesta di "pizza a New York" limitata a 5 risultati per pagina:
curl -X POST -d '{
"textQuery": "pizza in New York",
"pageSize": 5
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJifIePKtZwokRVZ-UdRGkZzs" }, { "id": "ChIJPxPd_P1YwokRfzLhSiACEoU" }, ... ], "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q" }
Per accedere alla pagina successiva dei risultati, utilizza pageToken per passare nextPageToken nel corpo della richiesta:
curl -X POST -d '{
"textQuery": "pizza in New York",
"pageSize": 5,
"pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw" }, { "id": "ChIJjaD94kFZwokR-20CXqlpy_4" }, ... ], "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c" }
Ottieni i descrittori dell'indirizzo
I descrittori di indirizzo forniscono informazioni relazionali sulla posizione di un luogo, inclusi i punti di riferimento nelle vicinanze e le aree contenenti.
L'esempio seguente mostra una richiesta di Ricerca testuale (nuova) per i luoghi vicino a un centro commerciale di San Jose. In questo esempio, includi addressDescriptors nella maschera di campo:
curl -X POST -d '{
"textQuery": "clothes",
"maxResultCount": 5,
"locationBias": {
"circle": {
"center": {
"latitude": 37.321328,
"longitude": -121.946275
}
}
},
"rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-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:searchText
La risposta include il luogo specificato nella richiesta, un elenco di punti di riferimento nelle vicinanze e la loro distanza dal luogo, nonché un elenco di aree e la loro relazione di contenimento con il luogo:
{ "places": [ { "displayName": { "text": "Urban Outfitters", "languageCode": "en" }, "addressDescriptor": { "landmarks": [ { "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "food", "movie_theater", "point_of_interest", "restaurant", "shoe_store", "shopping_mall", "store" ], "spatialRelationship": "WITHIN", "straightLineDistanceMeters": 133.72855 }, { "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": 250.99161 }, ... ], "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" }, ... ] } }, ... ] }
Trova le attività che apriranno in futuro
L'esempio seguente mostra una richiesta di Ricerca testuale (nuova) per le attività che apriranno in futuro a New Meadows, Idaho:
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 '{
"textQuery": "Roberts Greenhouse and Tree Farm",
"includeFutureOpeningBusinesses": true,
"maxResultCount": 20,
"locationBias": {
"circle": {
"center": {"latitude": 44.9755100, "longitude": -116.2842180},
"radius": 20
}
}
}' \
"https://places.googleapis.com/v1/places:searchText"
La risposta include le attività che apriranno in futuro, insieme al loro stato e alla data di apertura prevista:
{ "places": [ { "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "displayName": { "text": "Roberts Greenhouse and Tree Farm", "languageCode": "en" }, "openingDate": { "year": 2026, "month": 4, "day": 15 } } ] }
Ricevere informazioni sulle stazioni di transito
Puoi utilizzare Ricerca testuale (nuova) per trovare le stazioni di transito. Il corpo della risposta include informazioni sulla stazione, tra cui il nome, le aziende di trasporto pubblico affiliate e le linee di trasporto pubblico che servono la stazione. Inoltre, la risposta include un'icona del veicolo e i colori che puoi utilizzare per visualizzare le informazioni sulla stazione di transito.
L'esempio seguente mostra una richiesta per "Grand Central Station":
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 '{
"textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"
Il corpo della risposta include informazioni su ogni stazione all'interno del raggio, sulle linee servite dalla stazione, sugli avvisi emessi dalle aziende di trasporto pubblico in quella fermata e sulle informazioni sulle partenze:
{ "places": [ { "id": "ChIJhRwB-yFawokRi0AhGH87UTc", "displayName": { "text": "Grand Central", "languageCode": "en" }, "transitStation": { "displayName": { "text": "Grand Central", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "Metro-North Railroad", "languageCode": "en" }, "url": "http://www.mta.info/mnr", "lines": [ { "id": "ChIJOXpD29y2wokRryDO0CocwK0", "vehicleType": "HEAVY_RAIL", "displayName": { "text": "Harlem", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#0061AA", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg" }, "alerts": [ { "effect": "OTHER", "texts": [ { "headline": { "text": "Information", "languageCode": "en" }, "summary": { "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.", "languageCode": "en" }, "fullDescription": { "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.", "languageCode": "en" } } ], "detailsUrls": [ { "url": "https://new.mta.info/" } ], "cause": "OTHER_CAUSE", "startTime": "2026-04-16T04:00:00Z", "endTime": "2026-12-01T04:45:00Z", "attribution": { "link": { "text": "new.mta.info", "url": "https://new.mta.info/" } }, "createTime": "2026-05-15T22:39:30Z", "severityLevel": "INFO" } ] }, ... ] }, ... ] "stops": [ { "id": "ChIJOfdrigFZwokRJPllLwfPrJY", "location": { "latitude": 40.752823, "longitude": -73.977195999999992 }, "wheelchairAccessibleEntrance": true } ], "departureBoards": [ { "displayType": "TIME_CENTRIC", "rows": [ { "departures": [ { "timedDeparture": { "scheduledTime": "2026-05-15T22:42:00Z", "timingType": "SCHEDULED", "predictedTime": "2026-05-15T22:42:00Z", "updateTime": "2026-05-15T22:38:50Z" }, "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY", "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM" } ] }, ... ] } ] } }, { "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc", "displayName": { "text": "Grand Central Station", "languageCode": "en" } } ] }
Ottieni ingressi e punti di navigazione
Puoi richiedere ingressi e punti di navigazione per una destinazione. Gli ingressi definiscono i punti di entrata e di uscita di un luogo (ad esempio, i diversi gate di un aeroporto o di un centro commerciale). I punti di navigazione definiscono le posizioni lungo la strada in cui deve terminare la navigazione, il che è utile per indirizzare gli utenti verso il lato corretto della strada o un punto di arrivo specifico.
I punti di navigazione restituiscono un valore navigationPointToken. Puoi passare questo token all'SDK Navigation (disponibile per Android o iOS) o all'API Routes per guidare i conducenti verso quella posizione specifica. Per saperne di più, consulta Token dei punti di navigazione.
L'esempio seguente mostra una richiesta di Ricerca testuale (nuova) per "San Francisco International Airport" che include entrances e navigationPoints nella maschera di campo:
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 '{
"textQuery": "San Francisco International Airport",
"pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"
La risposta include gli ingressi e i punti di navigazione del luogo:
{ "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"] }, ... ] } ] }
Prova
Explorer API ti consente di effettuare richieste di esempio per familiarizzare con l'API e le relative opzioni.
Seleziona l'icona API api sul lato destro della pagina.
Se vuoi, modifica i parametri della richiesta.
Seleziona il pulsante Esegui. Nella finestra di dialogo, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona a schermo intero fullscreen per espandere la finestra di Explorer API.