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,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of mutually exclusive fields.
}
Campos
travelModes[]

enum (NavigationPoint.TravelMode)

Opcional. Os meios de transporte para filtrar os 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 da região, 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.

Consulte o destino principal. Pode ser um lugar, um endereço totalmente especificado ou um local LatLng. Alguns lugares e endereços com informações mínimas não podem ser transformados em destinos.

Os destinos são criados com base na consulta primária especificada.

Observação: só é possível usar lugares e endereços que podem ter um destino de navegação. 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. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
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.
Fim dos campos mutuamente exclusivos.

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 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of mutually exclusive fields.
}
Campos
A consulta de endereço. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
address

object (PostalAddress)

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

string

Um endereço formatado como uma única linha.
Fim dos campos mutuamente exclusivos.

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)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "location": {
    object (LatLng)
  }
  // End of mutually exclusive fields.
}
Campos
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Opcional. Filtros a serem aplicados aos candidatos de destino.
A consulta de local. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
location

object (LatLng)

Um local LatLng preciso.
Fim dos campos mutuamente exclusivos.

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 é extrair com mais facilidade os 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 condomínio de apartamentos que contém esse 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 informar 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 outras informações específicas sobre 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 do 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", "McDonald's"
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 desse lugar. Para lugares com polígonos de exibição, isso pode representar um bom ponto 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.

Esses valores são extraídos da tabela de tipos de endereço e de componentes de endereço usada pela API Places: https://developers.google.com/maps/documentation/places/web-service/place-types#address-types
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,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": {
    object (PlaceView)
  }
  // End of mutually exclusive fields.
}
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 desse 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.
O ponto de referência. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
place

object (PlaceView)

O lugar que representa esse ponto de referência.
Fim dos campos mutuamente exclusivos.

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 algumas centenas de 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 
{
  "displayName": {
    object (LocalizedText)
  },
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
Campos
displayName

object (LocalizedText)

Nome legível por humanos, por exemplo, "Portão B", "Entrada Sul", "Entrada da 5ª Avenida".
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 local 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 shopping, as entradas "PREFERRED" serão aquelas que provavelmente levam ao restaurante, enquanto as outras entradas retornadas serão outras entradas do prédio, como as de outros restaurantes no shopping.

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. Se uma entrada só dá acesso a uma loja na lateral do prédio, ela não é 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.