Ricerca di testo (novità)

Seleziona la piattaforma:Android iOS JavaScript Servizio web

Sviluppatori dello Spazio economico europeo (SEE)

Introduzione

Text Search (New) 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 a qualsiasi bias di posizione che è stato impostato.

Il servizio è particolarmente utile per eseguire query di indirizzi ambigui in un sistema automatizzato e i componenti non indirizzo della stringa possono corrispondere ad attività e indirizzi. Esempi di query di indirizzi ambigui sono indirizzi formattati in modo errato o richieste che includono componenti non indirizzo, ad esempio nomi di attività. Le richieste come i primi due esempi nella tabella seguente potrebbero restituire zero risultati a meno che non sia impostata una località, ad esempio regione, limitazione della località o preferenza della località.

"10 High Street, UK" o "123 Main Street, US" Più "High Street" nel Regno Unito; più "Main Street" negli Stati Uniti. La query non restituisce i risultati desiderati a meno che non sia impostata una limitazione della località.
"ChainRestaurant New York" Più sedi di "ChainRestaurant" a New York; nessun indirizzo o neanche nome della via.
"10 High Street, Escher UK" o "123 Main Street, Pleasanton US" Solo una "High Street" nella città di Escher nel Regno Unito; solo una "Main Street" nella città di Pleasanton, in California, negli Stati Uniti.
"UniqueRestaurantName New York" Un solo stabilimento con questo nome a New York; non è necessario un indirizzo per differenziarlo.
"pizzerie a New York" Questa query contiene la limitazione della località e "pizzerie" è un tipo di luogo ben definito. Restituisce più risultati.
"+1 514-670-8700"

Questa query contiene un numero di telefono. Restituisce più risultati per i luoghi associati a quel numero di telefono.

L'Explorer API ti consente di effettuare richieste live per familiarizzare con l'API e le relative opzioni:

Richieste di ricerca testuale (novità)

Una richiesta di ricerca di testo (nuova) è una richiesta HTTP POST del seguente formato:

https://places.googleapis.com/v1/places:searchText

Trasmetti 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)

Text Search (New) restituisce un oggetto JSON come risposta. Nella risposta:

  • L'array places contiene tutti i luoghi corrispondenti.
  • Ogni posizione nell'array è rappresentata da un oggetto Place. L'oggetto Place contiene informazioni dettagliate su un singolo luogo.
  • Il 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 di risposta. Passa la maschera del campo di risposta al metodo utilizzando il parametro URL $fields o fields oppure utilizzando l'intestazione HTTP X-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 assicurarsi di non richiedere 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 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 solo ID Text Search Essentials:

      places.attributions
      places.id
      places.name*
      nextPageToken

      * Il campo places.name contiene il nome risorsa del luogo nel formato: places/PLACE_ID. Utilizza places.displayName nello SKU Pro per accedere al nome testuale del luogo.

    • I seguenti campi attivano lo SKU Text Search Pro:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      places.adrFormatAddress
      places.businessStatus
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks**
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.location
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * I descrittori degli indirizzi sono generalmente disponibili per i clienti in India e sono sperimentali altrove.

      ** Il campo places.googleMapsLinks si trova nella fase di anteprima pre-GA e non è previsto alcun addebito, il che significa che la fatturazione è pari a 0 $per l'utilizzo durante l'anteprima.

    • I seguenti campi attivano lo SKU Text Search Enterprise:

      places.currentOpeningHours
      places.currentSecondaryOpeningHours
      places.internationalPhoneNumber
      places.nationalPhoneNumber
      places.priceLevel
      places.priceRange
      places.rating
      places.regularOpeningHours
      places.regularSecondaryOpeningHours
      places.userRatingCount
      places.websiteUri

    • I seguenti campi attivano lo SKU Text Search 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
      places.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 di testo e ricerca nelle vicinanze

  • textQuery

    La stringa di testo su cui eseguire la ricerca, ad esempio "ristorante", "Via Roma 123" o "il posto migliore da visitare a Roma". L'API restituisce le corrispondenze candidate in base a questa stringa e ordina i risultati in base alla loro pertinenza percepita.

Parametri facoltativi

  • includedType

    I risultati vengono orientati verso i luoghi che corrispondono al tipo specificato definito dalla tabella A. È possibile specificare un solo tipo. Ad esempio:

    • "includedType":"bar"
    • "includedType":"pharmacy"

    La ricerca di testo (nuova) applica il filtro per tipo a determinate query, a seconda dell'applicabilità. Ad esempio, il filtro per tipo potrebbe non essere applicato alle query per indirizzi specifici ("Via Principale 123"), ma viene quasi sempre applicato alle query categoriche ("negozi nelle vicinanze" o "centri commerciali").

    Per applicare il filtro per tipo a tutte le query, imposta strictTypeFiltering su true.

  • includePureServiceAreaBusinesses

    Se impostato su true, la risposta include le attività che visitano o effettuano consegne direttamente ai clienti, ma non hanno una sede fisica. Se impostato su false, 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 languageCode non viene fornito, l'API utilizza en come valore predefinito. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
    • L'API fa del suo meglio per fornire un indirizzo stradale leggibile sia per l'utente sia per gli abitanti del luogo. Per raggiungere questo obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in un sistema di scrittura leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. Tutti i componenti dell'indirizzo vengono restituiti nella stessa lingua, 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 geocoder 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 cercare. Questa posizione funge da bias, il che significa che possono essere restituiti risultati intorno alla posizione specificata, inclusi risultati al di fuori dell'area specificata.

    Puoi specificare locationRestriction o locationBias, ma non entrambi. Considera locationRestriction come la regione in cui devono trovarsi i risultati e locationBias come la regione in cui è probabile che si trovino i risultati, ma possono trovarsi anche al di fuori dell'area.

    Specifica la regione come viewport 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 viewport è considerato una regione chiusa, il che significa che include il suo confine. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi e i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi:

      • Se low = high, l'area visibile è costituita da un singolo punto.
      • Se low.longitude > high.longitude, l'intervallo di longitudine è invertito (l'area visibile attraversa la linea di longitudine di 180 gradi).
      • Se low.longitude = -180 gradi e high.longitude = 180 gradi, l'area visibile include tutte le longitudini.
      • Se low.longitude = 180 gradi e high.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 viewport vuoto genera un errore.

      Ad esempio, questa finestra completamente racchiude New York City:

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • locationRestriction

    Specifica un'area in cui cercare. I risultati al di fuori dell'area specificata non vengono restituiti.

    Specifica la regione come viewport rettangolare. Per un esempio di definizione dell'area visibile, vedi la descrizione di locationBias.

    Puoi specificare locationRestriction o locationBias, ma non entrambi. Considera locationRestriction come la regione in cui devono trovarsi i risultati e locationBias come la regione in cui è probabile che si trovino i risultati, ma possono trovarsi anche al di fuori dell'area.

  • maxResultCount (obsoleto)

    Specifica il numero di risultati (compreso tra 1 e 20) da visualizzare per pagina. Ad esempio, se imposti un valore maxResultCount pari a 5, verranno restituiti fino a 5 risultati nella prima pagina. Se la query può restituire altri risultati, la risposta include un nextPageToken che puoi passare a una richiesta successiva per accedere alla pagina successiva.

  • evOptions

    Specifica i parametri per l'identificazione dei connettori di ricarica e delle velocità di ricarica disponibili per i veicoli elettrici (EV).

    • 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 veicoli elettrici supportati includono caricabatterie combinati (CA e CC), caricabatterie Tesla, caricabatterie conformi a GB/T (per la ricarica rapida di veicoli elettrici in Cina) e caricabatterie per prese a muro. Per saperne di più, consulta la documentazione di riferimento.

      • Per filtrare i risultati in base a un connettore specifico supportato, imposta connectorTypes su quel valore. Ad esempio, per trovare i connettori di tipo 1 J1772, imposta connectorTypes su EV_CONNECTOR_TYPE_J1772.
      • Per filtrare i risultati per i connettori non supportati, imposta connectorTypes su EV_CONNECTOR_TYPE_OTHER.
      • Per filtrare i risultati per qualsiasi tipo di connettore che sia una presa a muro, imposta connectorTypes su EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
      • Per filtrare i risultati per qualsiasi tipo di connettore, imposta connectorTypes su EV_CONNECTOR_TYPE_UNSPECIFIED oppure non impostare un valore per connectorTypes.

    • minimumChargingRateKw

      Filtra i luoghi in base alla velocità di ricarica minima per veicoli elettrici in kilowatt (kW). Tutti i luoghi con una tariffa inferiore a quella minima vengono filtrati. Ad esempio, per trovare stazioni di ricarica 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 a 0,5. Ad esempio, un valore di 0,6 elimina tutti i risultati con una valutazione inferiore a 1,0.

  • openNow

    Se true, restituisci solo i luoghi aperti al pubblico al momento dell'invio della query. Se false, restituisci tutte le attività indipendentemente dallo stato di apertura. I luoghi che non specificano gli orari di apertura nel database di Google Places vengono restituiti se imposti questo parametro su false.

  • pageSize

    Specifica il numero di risultati (compreso tra 1 e 20) da visualizzare per pagina. Ad esempio, se imposti un valore pageSize pari a 5, verranno restituiti fino a 5 risultati nella prima pagina. Se la query può restituire altri risultati, la risposta include un nextPageToken che puoi passare a una richiesta successiva per accedere alla pagina successiva.

  • pageToken

    Specifica nextPageToken dal corpo della risposta della pagina precedente.

  • priceLevels

    Limita la ricerca ai luoghi contrassegnati a 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 è specificato priceLevels.

    Specifica un array di uno o più valori definiti da PriceLevel.

    Ad esempio:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • rankPreference

    Specifica come vengono classificati i risultati nella risposta in base al tipo di query:

    • Per una query categorica come "Ristoranti a New York", RELEVANCE (ordina i risultati in base alla pertinenza della ricerca) è l'impostazione predefinita. Puoi impostare rankPreference su RELEVANCE o DISTANCE (i risultati vengono classificati in base alla distanza).
    • Per una query non categorica come "Mountain View, CA", ti consigliamo di lasciare rankPreference non impostato.

  • regionCode

    Il codice regione utilizzato per formattare la risposta, specificato come valore di un codice CLDR a due caratteri. Questo parametro può anche avere un effetto di distorsione sui risultati di ricerca. Non esiste un valore predefinito.

    Se il nome del paese del campo formattedAddress nella risposta corrisponde a regionCode, il codice paese viene omesso da formattedAddress. Questo parametro non ha effetto su adrFormatAddress, che include sempre il nome del paese quando disponibile, né su shortFormattedAddress, che non lo include mai.

    La maggior parte dei codici CLDR sono identici ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il TLD specifico per paese 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 su true, vengono restituiti solo i luoghi che corrispondono ai tipi specificati da includeType. Se il valore è false (impostazione predefinita), la risposta può contenere luoghi che non corrispondono ai tipi specificati.

Esempi di ricerca testuale (nuova)

Trovare un luogo tramite la stringa di query

L'esempio seguente mostra una richiesta di ricerca di testo (nuova) per "Cucina vegetariana 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 è quindi 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"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Aggiungi altri tipi di dati alla maschera del 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"
      }
    },
    ...
  ]
}

Filtrare i luoghi in base al livello di prezzo

Utilizza l'opzione priceLevel per filtrare i risultati in modo da visualizzare solo i ristoranti definiti economici o a prezzi moderati:

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 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.

Limitare la ricerca a un'area specifica

Utilizza locationRestriction o locationBias, ma non entrambi, per limitare una ricerca a un'area. Considera locationRestriction come la regione in cui devono trovarsi i risultati e locationBias come la regione in cui devono trovarsi i risultati, ma possono essere al di fuori dell'area.

Limitare l'area utilizzando locationRestriction

Utilizza il parametro locationRestriction per limitare i risultati della query a una regione specifica. 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 di testo (nuova) per "cibo vegetariano" a New York City. 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'

Dare la priorità a un'area utilizzando locationBias

L'esempio seguente mostra una richiesta di ricerca di testo (nuova) per "cibo vegetariano" con un bias per una 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'

Cercare stazioni di ricarica EV con una velocità di ricarica minima

Utilizza minimumChargingRateKw e connectorTypes per cercare luoghi con caricabatterie disponibili compatibili con il tuo veicolo elettrico.

L'esempio seguente mostra una richiesta di connettori di ricarica per veicoli elettrici 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"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "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"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

Cercare attività al domicilio del cliente

Utilizza il parametro includePureServiceAreaBusinesses per cercare attività senza un indirizzo del servizio fisico (ad esempio, un servizio di pulizia mobile o un food truck).

Il seguente esempio 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"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

Specifica un numero di risultati da restituire per pagina

Utilizza il parametro pageSize per specificare il 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.

Il seguente esempio 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"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

Per accedere alla pagina successiva dei risultati, utilizza pageToken per inserire 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"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

Recupera i descrittori dell'indirizzo

I descrittori di indirizzo forniscono informazioni relazionali sulla posizione di un luogo, inclusi punti di riferimento nelle vicinanze e aree contenute.

L'esempio seguente mostra una richiesta di ricerca di testo (nuova) per luoghi vicino a un centro commerciale a San Jose. In questo esempio, includi addressDescriptors nella maschera del 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
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "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": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

Prova

L'Explorer API ti consente di effettuare richieste di esempio per familiarizzare con l'API e le relative opzioni.

  1. Seleziona l'icona API api sul lato destro della pagina.

  2. (Facoltativo) Modifica i parametri della richiesta.

  3. Seleziona il pulsante Esegui. Nella finestra di dialogo, scegli l'account che vuoi utilizzare per effettuare la richiesta.

  4. Nel riquadro Explorer API, seleziona l'icona a schermo intero fullscreen per espandere la finestra di Explorer API.