Method: geocode.destinations.searchDestinations

Esse método realiza uma pesquisa de destino e retorna uma lista de destinos.

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação 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.
}
Campos
travelModes[]

enum (NavigationPoint.TravelMode)

Opcional. Os modos de viagem para filtrar pontos de navegação. Isso influencia o campo navigationPoints retornado na resposta. Se estiver vazio, os pontos de navegação de todos os meios de transporte serão retornados.
languageCode

string

Opcional. Idioma em que os resultados devem ser retornados.
regionCode

string

Opcional. Código da região. O código regional, especificado como um valor ccTLD ("domínio de nível superior") de dois caracteres. O parâmetro afeta os resultados com base na legislação aplicável. Esse parâmetro também influencia, mas não restringe totalmente, os resultados do serviço.

Campo de união primary_query. Consulte o destino principal. Pode ser um lugar, um endereço totalmente especificado ou um local LatLng. Alguns lugares e endereços com poucas informações não podem ser transformados em um destino.

Os destinos são criados com base na consulta principal especificada.

Observação: somente lugares e endereços que podem ter um destino de navegação são aceitos. Por exemplo, um lugar que representa uma casa ou um complexo de apartamentos pode ser usado como consulta principal, mas lugares que representam uma localidade ou uma área político-administrativa não podem ser usados como consulta principal. primary_query pode ser apenas de um dos tipos a seguir:
place

string

O nome do recurso de um lugar, no formato places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

Um endereço.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

Um local exato.

Corpo da resposta

Mensagem de resposta para DestinationService.SearchDestinations.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
Campos
destinations[]

object (Destination)

Uma lista de destinos.

O serviço vai retornar um resultado se um destino principal puder ser identificado de forma inequívoca na consulta principal. Caso contrário, o serviço poderá retornar vários resultados para desambiguação ou nenhum resultado.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

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

SearchDestinationsRequest.AddressQuery

O endereço que você quer pesquisar. Especifique endereços de acordo com o formato usado pelo serviço postal do país em questão.

Representação 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.
}
Campos
Campo de união kind. A consulta de endereço. kind pode ser apenas de um dos tipos a seguir:
address

object (PostalAddress)

Um endereço de rua no formato de endereço postal.
addressQuery

string

Um endereço formatado como uma única linha.

SearchDestinationsRequest.LocationQuery

Uma consulta de local para identificar um destino principal próximo.

Observação: se a consulta de local estiver em um edifício que contém subinstalações, é possível que o lugar principal retornado seja uma subinstalação. Nesses casos, o campo containingPlaces vai incluir o prédio.

Representação 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.
}
Campos
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Opcional. Filtros a serem aplicados aos candidatos de destino.
Campo de união kind. A consulta de local. kind pode ser apenas de um dos tipos a seguir:
location

object (LatLng)

Um local LatLng preciso.

SearchDestinationsRequest.LocationQuery.PlaceFilter

Filtros a serem aplicados aos candidatos de destino.

Representação JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
Campos
structureType

enum (PlaceView.StructureType)

Opcional. Se especificado, todos os destinos terão um lugar principal com esse tipo de estrutura. Isso pode resultar na filtragem de alguns destinos ou na simplificação/refinamento dos destinos retornados.

Por exemplo, se GROUNDS for especificado, todos os destinos retornados terão um lugar principal com o tipo de estrutura GROUNDS. Isso pode resultar na filtragem de alguns destinos que não fazem parte de um terreno ou na aproximação dos destinos retornados para o nível do terreno.

Outro uso desse campo é facilitar a extração de polígonos de exibição de edifícios. Por exemplo, se BUILDING for especificado, o polígono de exibição do lugar principal será o do edifício no local especificado.
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

Opcional. Se especificado, retorna apenas os destinos que atendem aos critérios de endereçamento correspondentes.

PlaceView.StructureType

O tipo de estrutura que esse lugar representa.

Tipos enumerados
STRUCTURE_TYPE_UNSPECIFIED Não utilizado.
POINT Um local de ponto.
SECTION Uma subseção de um edifício.
BUILDING Um edifício.
GROUNDS Uma área grande que geralmente contém vários edifícios, como um campus universitário, um complexo de apartamentos ou um shopping center.

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

Define opções para filtragem de endereçamento. Novos valores podem ser adicionados no futuro.

Tipos enumerados
ADDRESSABILITY_UNSPECIFIED Quando não especificado, o serviço escolhe um padrão razoável.
ANY A capacidade de endereçamento não é um critério de filtragem. Os destinos são retornados independentemente da capacidade de endereçamento.
PRIMARY Todos os destinos retornados terão um lugar principal com um endereço ou nome de rua.
WEAK Todos os destinos retornados terão um lugar principal ou um subdestino com um endereço ou nome de rua.

Destino

Um destino. Isso inclui o lugar principal, lugares relacionados, entradas e pontos de navegação.

Representação JSON 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ]
}
Campos
primary

object (PlaceView)

O lugar principal identificado pelo primary_query na solicitação.
containingPlaces[]

object (PlaceView)

Os lugares menos precisos que contêm o lugar principal. Por exemplo, o complexo de apartamentos que contém este prédio.
subDestinations[]

object (PlaceView)

Subdestinos mais precisos do lugar principal. Por exemplo, unidades contidas em um edifício.

Observação: em comparação com o SubDestination retornado pela API Places, essa lista de subdestinos é mais completa, e cada subdestino contém mais informações.
landmarks[]

object (Landmark)

Pontos de referência que podem ser usados para comunicar onde fica o destino ou ajudar na chegada.
entrances[]

object (Entrance)

Entradas para este destino.
navigationPoints[]

object (NavigationPoint)

Pontos de navegação para este destino.

PlaceView

Representa uma visualização de um lugar na API Places. Ele também fornece informações adicionais específicas para destinos, como o tipo de estrutura e o polígono de exibição.

Em alguns casos, um PlaceView com o mesmo ID de lugar pode ser diferente do que é retornado pela API Places para os campos types e displayName.

Representação JSON 
{
  "place": string,
  "placeId": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  },
  "addressComponents": [
    {
      object (PlaceView.AddressComponent)
    }
  ]
}
Campos
place

string

O nome do recurso deste lugar, no formato places/{placeId}. Pode ser usado para procurar o lugar.
placeId

string

O identificador exclusivo de um lugar.
displayName

object (LocalizedText)

Descrição do lugar legível por humanos. Por exemplo, "Portão B", "McDonalds"
primaryType

string

O tipo principal desse lugar. Consulte https://developers.google.com/maps/documentation/places/web-service/place-types para ver a lista de valores possíveis.

Observação: esse campo nem sempre é preenchido. Esteja preparado para usar o campo types nessas situações.
types[]

string

Todos os tipos de lugar associados a este lugar. Consulte https://developers.google.com/maps/documentation/places/web-service/place-types para ver a lista de valores possíveis.
formattedAddress

string

Endereço de uma linha.
postalAddress

object (PostalAddress)

Endereço estruturado.
structureType

enum (PlaceView.StructureType)

O tipo de estrutura correspondente a esse lugar.
location

object (LatLng)

O local deste lugar. Para lugares com polígonos de exibição, isso pode representar um bom local para colocar um marcador no mapa.
displayPolygon

object (Struct format)

O contorno do polígono do lugar no formato GeoJSON, usando o formato RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Observação: o formato RFC 7946 é compatível com MultiPolygons, então um objeto displayPolygon pode representar vários polígonos.
addressComponents[]

object (PlaceView.AddressComponent)

Componentes repetidos para cada nível de localidade.

PlaceView.AddressComponent

Os componentes estruturados que formam o endereço formatado, se essas informações estiverem disponíveis.

Representação JSON 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
Campos
longText

string

A descrição completa em texto ou o nome do componente do endereço. Por exemplo, um componente de endereço para o país Austrália pode ter o nome longo "Austrália".
shortText

string

Um nome abreviado, no formato de texto, para o componente de endereço, se estiver disponível. Por exemplo, um componente de endereço para o país Austrália pode ter o nome abreviado "AU".
types[]

string

Uma matriz que indica os tipos do componente de endereço.

Consulte https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types para mais detalhes.
languageCode

string

O idioma usado para formatar esse componente, na notação CLDR.

Ponto de referência

Os pontos de referência são usados para informar onde fica o destino ou ajudar a chegar até ele.

Representação 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.
}
Campos
relationalDescription

object (LocalizedText)

Uma descrição legível por humanos de como o destino se relaciona com o ponto de referência. Por exemplo: "Perto do Empire State Building" ou "Em frente à Casa Branca".
tags[]

enum (Landmark.Tag)

Tags que descrevem como o ponto de referência pode ser usado no contexto do destino.
straightLineDistanceMeters

number

Apenas saída. A distância em linha reta do ponto de referência até o destino, em metros.
travelDistanceMeters

number

Apenas saída. A distância a pé desse ponto de referência até o destino, em metros.
Campo de união landmark. O ponto de referência. landmark pode ser apenas de um dos tipos a seguir:
place

object (PlaceView)

O lugar que representa esse ponto de referência.

Landmark.Tag

A lista de todas as tags possíveis que descrevem como um ponto de referência pode ser usado no contexto de um destino.

Se um endereço tiver as tags ADDRESS e ARRIVAL, isso significa que o ponto de referência é importante no local e está perto do destino.

Tipos enumerados
TAG_UNSPECIFIED Não utilizado.
ADDRESS Um lugar de destaque local que pode ser usado para identificar a localização geral do destino. Normalmente, a poucos metros do destino. Eles são semelhantes aos pontos de referência retornados pelo recurso de descritores de endereço da API Geocoding: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL Um lugar que pode ser usado para ajudar a chegar ao destino. Útil para navegação quando você está perto do destino. Por exemplo, esse ponto de referência pode ser um lugar do outro lado da rua do destino. Um ponto de referência com essa tag geralmente está mais próximo do destino do que os pontos com a tag ADDRESS.

Entrada

Uma entrada é um único par de coordenadas de latitude/longitude que define o local de um ponto de entrada e saída de um lugar.

Representação JSON 
{
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
Campos
location

object (LatLng)

O local da entrada.
tags[]

enum (Entrance.Tag)

Uma lista de tags que descrevem a entrada.
place

string

A estrutura em que essa entrada está localizada fisicamente, no formato places/{placeId}.

Entrance.Tag

Características que descrevem uma entrada.

Tipos enumerados
TAG_UNSPECIFIED Não utilizado.
PREFERRED

A entrada provavelmente fornece acesso físico ao lugar principal no destino retornado. Um lugar pode ter várias entradas preferenciais. Se uma entrada não tiver essa tag, significa que ela está fisicamente no mesmo edifício que o lugar principal, mas não necessariamente dá acesso a ele.

Por exemplo, se o lugar principal for um restaurante em um centro comercial, as entradas "PREFERIDAS" serão as que provavelmente levam ao restaurante, enquanto as outras entradas retornadas serão outras entradas do edifício, como as de outros restaurantes no centro comercial.

Se o lugar principal for um edifício, as entradas do PREFERRED serão aquelas que levam à parte "principal" do edifício. Por exemplo, em um shopping center, as entradas PREFERRED são aquelas que dão acesso ao saguão principal. No entanto, se uma entrada só dá acesso a uma loja na lateral do prédio, ela não é uma entrada PREFERRED.

Observação: uma entrada PREFERRED pode não dar acesso ao lugar principal, e uma entrada que não é PREFERRED pode dar acesso ao lugar principal.