Method: geocode.destinations.searchDestinations

Questo metodo esegue una ricerca della destinazione e restituisce un elenco di destinazioni.

Richiesta HTTP

POST https://geocode.googleapis.com/v4alpha/geocode/destinations

L'URL utilizza la sintassi di transcodifica gRPC.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // Union field primary_query can be only one of the following:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of list of possible types for union field primary_query.
}
Campi
travelModes[]

enum (NavigationPoint.TravelMode)

Facoltativo. Le modalità di viaggio per cui filtrare i punti di navigazione. Ciò influisce sul campo navigationPoints restituito nella risposta. Se è vuoto, possono essere restituiti i punti di navigazione di tutte le modalità di viaggio.
languageCode

string

Facoltativo. La lingua in cui devono essere restituiti i risultati.
regionCode

string

Facoltativo. Codice regione. Il codice regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Il parametro influisce sui risultati in base alla legge vigente. Questo parametro influenza anche, ma non limita completamente, i risultati del servizio.

Campo unione primary_query. Esegui una query per la destinazione principale. Può trattarsi di un luogo, di un indirizzo specificato in modo completo o di una posizione LatLng. Alcuni luoghi e indirizzi con informazioni minime non potranno essere trasformati in una destinazione.

Le destinazioni sono create in base alla query principale specificata.

Nota: sono supportati solo i luoghi e gli indirizzi che possono avere una destinazione di navigazione. Ad esempio, un luogo che rappresenta una casa o un complesso di appartamenti può essere utilizzato come query principale, ma i luoghi che rappresentano una località o un'area amministrativa non possono essere utilizzati come query principale. primary_query può essere solo uno dei seguenti tipi:
place

string

Il nome risorsa di un luogo, nel formato places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

Indirizzo e numero civico.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

Una posizione esatta.

Corpo della risposta

Messaggio di risposta per DestinationService.SearchDestinations.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
Campi
destinations[]

object (Destination)

Un elenco di destinazioni.

Il servizio restituisce un risultato se una destinazione principale può essere identificata in modo univoco dalla query principale. In caso contrario, il servizio potrebbe restituire più risultati per la disambiguazione o nessun risultato.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/maps-platform.geocode

SearchDestinationsRequest.AddressQuery

L'indirizzo della via che vuoi cercare. Specifica gli indirizzi in conformità al formato utilizzato dal servizio postale nazionale del paese interessato.

Rappresentazione JSON 
{

  // Union field kind can be only one of the following:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of list of possible types for union field kind.
}
Campi
Campo unione kind. La query dell'indirizzo. kind può essere solo uno dei seguenti tipi:
address

object (PostalAddress)

Un indirizzo e numero civico nel formato dell'indirizzo postale.
addressQuery

string

Un indirizzo formattato come una singola riga.

SearchDestinationsRequest.LocationQuery

Una query sulla posizione per identificare una destinazione principale nelle vicinanze.

Nota: se la query sulla posizione si trova all'interno di un edificio che contiene locali secondari, è possibile che il luogo principale restituito sia un locale secondario. In questi casi, il campo containingPlaces includerà l'edificio.

Rappresentazione JSON 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
Campi
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Facoltativo. Filtri da applicare alle destinazioni candidate.
Campo unione kind. La query sulla posizione. kind può essere solo uno dei seguenti tipi:
location

object (LatLng)

Una posizione LatLng esatta.

SearchDestinationsRequest.LocationQuery.PlaceFilter

Filtri da applicare alle destinazioni candidate.

Rappresentazione JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
Campi
structureType

enum (PlaceView.StructureType)

Facoltativo. Se specificato, tutte le destinazioni hanno garantito un luogo principale con questo tipo di struttura. Ciò può comportare il filtraggio di alcune destinazioni o l'affinamento/l'approssimazione delle destinazioni restituite.

Ad esempio, se viene specificato GROUNDS, tutte le destinazioni restituite avranno un luogo principale con il tipo di struttura GROUNDS. Ciò può comportare il filtraggio di alcune destinazioni che non fanno parte di un complesso o l'approssimazione delle destinazioni restituite al livello del complesso.

Un altro utilizzo di questo campo è l'estrazione più semplice dei poligoni di visualizzazione degli edifici. Ad esempio, se viene specificato BUILDING, il poligono di visualizzazione del luogo principale sarà quello dell'edificio nella posizione specificata.
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

Facoltativo. Se specificato, restituisce solo le destinazioni che soddisfano i criteri di indirizzabilità corrispondenti.

PlaceView.StructureType

Il tipo di struttura rappresentato da questo luogo.

Enum
STRUCTURE_TYPE_UNSPECIFIED Non utilizzato.
POINT Una posizione puntuale.
SECTION Una sottosezione di un edificio.
BUILDING Un edificio.
GROUNDS Un'area di grandi dimensioni che in genere contiene più edifici, come un campus universitario, un complesso di appartamenti o un centro commerciale.

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

Definisce le opzioni per il filtro di indirizzabilità. In futuro potrebbero essere aggiunti nuovi valori.

Enum
ADDRESSABILITY_UNSPECIFIED Se non specificato, il servizio sceglierà un valore predefinito ragionevole.
ANY L'indirizzabilità non è un criterio di filtro. Le destinazioni vengono restituite indipendentemente dalla loro indirizzabilità.
PRIMARY Tutte le destinazioni restituite avranno un luogo principale con un indirizzo o un nome a livello di strada.
WEAK Tutte le destinazioni restituite avranno un luogo principale o una sottodestinazione con un indirizzo o un nome a livello di strada.

Destinazione

Una destinazione. Sono inclusi il luogo principale, i luoghi correlati, gli ingressi e i punti di navigazione.

Rappresentazione JSON 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ],
  "arrivalSummary": {
    object (Destination.ArrivalSummary)
  }
}
Campi
primary

object (PlaceView)

Il luogo principale identificato da primary_query nella richiesta.
containingPlaces[]

object (PlaceView)

I luoghi meno precisi in cui è contenuta la località principale. Ad esempio, il complesso di appartamenti che contiene questo edificio.
subDestinations[]

object (PlaceView)

Destinazioni secondarie più precise del luogo principale. Ad esempio, le unità contenute in un edificio.

Nota: rispetto a SubDestination restituito dall'API Places, questo elenco di sub-destinazioni è più esaustivo e ogni sub-destinazione contiene più informazioni.
landmarks[]

object (Landmark)

Punti di riferimento che possono essere utilizzati per comunicare la posizione della destinazione o per facilitare l'arrivo.
entrances[]

object (Entrance)

Ingressi per questa destinazione.
navigationPoints[]

object (NavigationPoint)

Punti di navigazione per questa destinazione.
arrivalSummary

object (Destination.ArrivalSummary)

Riepilogo dell'esperienza di arrivo a destinazione creato con l'AI.

PlaceView

Rappresenta una visualizzazione di un luogo nell'API Places. Fornisce inoltre informazioni aggiuntive specifiche per le destinazioni, come il tipo di struttura e il poligono di visualizzazione.

In alcuni casi, un PlaceView con lo stesso ID luogo potrebbe differire da ciò che viene restituito dall'API Places per i campi types e displayName.

Rappresentazione JSON 
{
  "place": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  }
}
Campi
place

string

Il nome risorsa di questo luogo, nel formato places/{placeId}.
displayName

object (LocalizedText)

Descrizione del luogo leggibile. Ad esempio, "Gate B", "McDonalds"
primaryType

string

Il tipo di luogo principale di questo luogo. Per l'elenco dei valori possibili, consulta la pagina https://developers.google.com/maps/documentation/places/web-service/place-types.

Nota: questo campo non viene compilato sempre. In queste situazioni, preparati a utilizzare il campo types.
types[]

string

Tutti i tipi di luoghi associati a questo luogo. Per l'elenco dei valori possibili, consulta la pagina https://developers.google.com/maps/documentation/places/web-service/place-types.
formattedAddress

string

Indirizzo su una sola riga.
postalAddress

object (PostalAddress)

Indirizzo strutturato.
structureType

enum (PlaceView.StructureType)

Il tipo di struttura corrispondente a questo luogo.
location

object (LatLng)

La posizione di questo luogo. Per i luoghi con poligoni di visualizzazione, questo può rappresentare un buon punto per posizionare un indicatore sulla mappa.
displayPolygon

object (Struct format)

Il contorno poligonale del luogo in formato GeoJSON, utilizzando il formato RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Nota: il formato RFC 7946 supporta i MultiPolygon, quindi un oggetto displayPolygon può rappresentare più poligoni.

Punto di riferimento

I punti di riferimento vengono utilizzati per comunicare dove si trova la destinazione o per aiutarti ad arrivarci.

Rappresentazione JSON 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
Campi
relationalDescription

object (LocalizedText)

Una descrizione leggibile di come la destinazione si relaziona al punto di riferimento. Ad esempio: "Vicino all'Empire State Building" o "Di fronte alla Casa Bianca".
tags[]

enum (Landmark.Tag)

Tag che descrivono come può essere utilizzato il punto di riferimento nel contesto della destinazione.
straightLineDistanceMeters

number

Solo output. La distanza in linea retta da questo punto di riferimento alla destinazione in metri.
travelDistanceMeters

number

Solo output. La distanza dalla rete stradale da questo punto di riferimento alla destinazione in metri.
Campo unione landmark. Il punto di riferimento. landmark può essere solo uno dei seguenti tipi:
place

object (PlaceView)

Il luogo che rappresenta questo punto di riferimento.

Landmark.Tag

L'elenco di tutti i tag possibili che descrivono come può essere utilizzato un punto di riferimento nel contesto di una destinazione.

Se un indirizzo ha sia i tag ADDRESS che ARRIVAL, significa che il punto di riferimento è importante a livello locale e vicino alla destinazione.

Enum
TAG_UNSPECIFIED Non utilizzato.
ADDRESS Un luogo di rilievo locale che può essere utilizzato per identificare la posizione generale della destinazione. In genere entro poche centinaia di metri dalla destinazione. Questi sono simili ai punti di riferimento restituiti dalla funzionalità Descrittori di indirizzi dell'API Geocoding: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL Un luogo che può essere utilizzato per raggiungere la destinazione. Utile per la navigazione quando ti trovi nelle vicinanze della destinazione. Ad esempio, questo punto di riferimento potrebbe essere un luogo che si trova di fronte alla destinazione. Un punto di riferimento con questo tag è in genere più vicino alla destinazione rispetto ai punti di riferimento con il tag ADDRESS.

Ingresso

Un ingresso è una singola coppia di coordinate di latitudine/longitudine che definisce la posizione di un punto di ingresso e di uscita per un luogo.

Rappresentazione JSON 
{
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
Campi
location

object (LatLng)

La posizione dell'ingresso.
tags[]

enum (Entrance.Tag)

Un elenco di tag che descrivono l'ingresso.
place

string

La struttura su cui si trova fisicamente questo ingresso, in formato places/{placeId}.

Entrance.Tag

Caratteristiche che descrivono un ingresso.

Enum
TAG_UNSPECIFIED Non utilizzato.
PREFERRED

L'ingresso probabilmente fornisce l'accesso fisico al luogo principale nella destinazione restituita. Un luogo può avere più ingressi preferiti. Se un ingresso non ha questo tag, significa che si trova fisicamente nello stesso edificio del luogo principale, ma non fornisce necessariamente l'accesso al luogo.

Ad esempio, se il luogo principale è un ristorante in un centro commerciale, gli ingressi "PREFERITI" saranno quelli che probabilmente conducono al ristorante stesso, mentre gli altri ingressi restituiti saranno altri ingressi dell'edificio, ad esempio quelli di altri ristoranti del centro commerciale.

Se il luogo principale è un edificio, gli ingressi PREFERRED saranno quelli che conducono alla parte "principale" dell'edificio. Ad esempio, in un centro commerciale gli ingressi PREFERRED saranno quelli che consentono l'accesso all'atrio principale, ma se un ingresso fornisce l'accesso solo a un negozio sul lato dell'edificio, non sarà un ingresso PREFERRED.

Nota: un ingresso PREFERRED potrebbe non fornire l'accesso al luogo principale, mentre un ingresso non PREFERRED potrebbe fornire l'accesso al luogo principale.

Destination.ArrivalSummary

Riepilogo dell'esperienza di arrivo a destinazione creato con l'AI.

Rappresentazione JSON 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
Campi
text

object (LocalizedText)

Il riepilogo dell'esperienza di arrivo a destinazione.
flagContentUrl

string

Un link in cui gli utenti possono segnalare un problema con il riepilogo.
disclosureText

object (LocalizedText)

Solo output. Contiene il testo dell'informativa per il riepilogo dell'arrivo.