Usar a API Region Lookup

Com a API Region Lookup, você pode encontrar IDs de lugares para regiões, que podem ser usados na estilização dos polígonos de limites com base em dados. A API Region Lookup é compatível com dois tipos de solicitação:

  • A Region lookup procura uma região por nome de lugar, código FIPS (somente estados e condados dos EUA) ou código do país ISO-3166-1 (ambos os links em inglês).
  • A Region search procura a região que contém um local específico, como especificado por um endereço, LatLng ou ID do lugar.

Tipos de região compatíveis

Os seguintes tipos de região são compatíveis: country, administrative_area_level_1, administrative_area_level_2, postal_code e locality.

Instalar a biblioteca

Para usar a API Region Lookup, siga estas etapas:

  1. Ative a API Region Lookup no console.
  2. Instale a biblioteca de código aberto: npm install @googlemaps/region-lookup

Importar dependências da biblioteca

A biblioteca de código aberto Region Lookup fornece um conjunto de funções e tipos TypeScript que você precisa importar para o código.

  • Para solicitações Region lookup, importe o seguinte:

    import {
  lookupRegion,
  LookupRegionRequestData,
  LookupRegionResponseData,
  LookupRegionResponse,
  RegionIdentifier
} from "@googlemaps/region-lookup";

  • Para solicitações Region search, importe o seguinte:

    import {
  searchRegion,
  RegionSearchValue,
  SearchRegionRequestData,
  SearchRegionResponse
} from "@googlemaps/region-lookup";

Solicitações de Region lookup

Uma solicitação Region lookup usa um nome de lugar ou código de identificador e retorna um ID de lugar. Para procurar uma região, chame lookupRegion(), especificando um LookupRegionRequestData com os seguintes parâmetros:

  • place ou unit_code (obrigatório) – O nome da região (place) ou unit_code do lugar. O unit_code pode ser um código FIPS (somente estados e condados dos EUA) ou o código de país ISO-3166-1.
  • place_type (obrigatório) – O valor do tipo de lugar que será pesquisado.
  • region_code – Código de país/região ISO-3166 de duas letras do local a ser correspondido. O region_code é opcional se place_type é COUNTRY.
  • language – O código de idioma BCP-47, como "pt-BR" ou "en-US". Se nenhum for especificado, o padrão será "en-US".

O exemplo a seguir mostra uma solicitação de pesquisa para Newark, NJ.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};
const data: LookupRegionRequestData = {
  identifiers: [
    {
      "place": "newark",
      "place_type": "locality",
      "region_code": "us",
      "language": "en",
    },
  ],
};
const response: LookupRegionResponse = await RegionLookup.lookupRegion({ headers, data });

O parâmetro place ou unit_code é obrigatório. Se nenhum for especificado, será retornado um erro.

O parâmetro region_code é obrigatório, a menos que place_type seja COUNTRY.

place e unit_code especificam um local para corresponder ao ID de lugar. Por exemplo, se place for "Califórnia" e place_type for ADMINISTRATIVE_AREA_LEVEL_1, a API vai retornar o ID de lugar da Califórnia como matched_place_id:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

    Resultados de matched_place_id: ID de lugar da Califórnia. Todos os outros tipos compatíveis não retornam correspondências.

Se unit_code for "6" (código FIPS da Califórnia), place_type for ADMINISTRATIVE_AREA_LEVEL_1 e region_code for "US", a API vai retornar o ID de lugar da Califórnia:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

    Resultados de matched_place_id: ID de lugar da Califórnia. Todos os outros tipos compatíveis não retornam correspondências.

Se unit_code for "US", a API vai retornar os seguintes resultados quando os seguintes place_types forem especificados:

  • place_type: COUNTRY

    Resultados de matched_place_id: ID de lugar dos Estados Unidos. Todos os outros tipos compatíveis não retornam correspondências.

Se nenhuma correspondência for encontrada, o matched_place_id não será definido.

Os IDs de lugar candidatos são retornados quando há ambiguidade. Por exemplo, se place for "Condado de Santa Clara" e place_type for LOCALITY, o ID de lugar do Condado de Santa Clara será retornado como candidato.

Resposta da Region lookup

O objeto LookupRegionResponse vai conter um matched_place_id se um resultado for encontrado. Se nenhum resultado for encontrado, IDs de lugar de menor confiança serão retornados como IDs candidatos, com um código de erro contendo informações de depuração.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

Solicitações de Region search

Para encontrar uma região que contenha um local específico, chame searchRegion especificando um SearchRegionRequestData com os seguintes parâmetros:

  • address ou latlng ou place_id (obrigatório) – Contém uma string de endereço não estruturada, latlng ou ID do lugar contidos na região (por exemplo, PDI, edifício etc.). Se nenhum for especificado, será retornado um erro.
  • place_type (obrigatório) – O valor do tipo de lugar para o tipo de região a ser pesquisada.
  • region_code – Código de país/região ISO-3166 de duas letras do local a ser correspondido. O region_code é necessário quando address é especificado.
  • language – O código de idioma BCP-47, como "pt-BR" ou "en-US". Se nenhum for especificado, o padrão será "en-US".

O exemplo a seguir mostra uma solicitação de pesquisa para Burbank, CA.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};

const data: SearchRegionRequestData = {
  search_values: [
    {
      "address": "2627 N Hollywood Way, Burbank, CA" ,
      "place_type": "locality" as const,
      "region_code": "us"
    },
  ],
};
const response = await regionLookupClient.searchRegion({ headers, data });

Resposta da Region search

O objeto SearchRegionResponse vai conter um matched_place_id se um resultado for encontrado. Caso não haja correspondência, a resposta vai mostrar um ou mais IDs de lugar candidatos e um código de erro.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

Referência

Identificadores LookupRegionRequestData

Campo Tipo Descrição
place string O nome da região a ser associada a um ID de lugar. Use o campo place em combinação com place_type para procurar o ID de lugar da região. Por exemplo, se place_type for "região administrativa", um place válido poderá ser "Palo Alto, CA". Se place_type for POSTAL_CODE, um place_name válido poderá ser "94109". Se place_type for COUNTRY, um place válido poderá ser "Estados Unidos" etc. O region_code é obrigatório quando o place é especificado, a menos que o place_type seja COUNTRY.
unit_code string O código de estado ou condado FIPs (somente nos EUA) ou o código de país ISO-3166-1 a ser correspondido. O campo unit_code é usado com place_type para procurar o ID de lugar da região. Por exemplo: se o place_type for COUNTRY, um unit_code válido poderá ser "US" (código ISO-3166-1 Alpha-2 para os Estados Unidos) ou "BR" (código ISO-3166-1 Alpha-2 para o Brasil). Se o place_type for ADMINISTRATIVE_AREA_LEVEL_1 (estado) e o region_code for "US", um unit_code válido poderá ser "6" (código FIPs para Califórnia) ou "12"(código FIPs para Flórida). Se o place_type for ADMINISTRATIVE_AREA_LEVEL_2 (condado) e o region_code for "US", o unit_code válido poderá ser "6001" (código FIPs do Condado de Alameda na Califórnia) ou "12086" (código FIPs para o Condado de Miami-Dade na Flórida). É preciso informar o region_code ao especificar um código FIPs. O region_code é ignorado para códigos de país ISO-3166-1.
place_type PlaceType Obrigatório. O tipo de região a ser correspondida.
region_code string Código ISO-3166 de país/região de duas letras para o local que você está tentando corresponder. O campo region_code será opcional se o place_type for COUNTRY.
language_code string O código de idioma BCP-47, como "en-US" ou "sr-Latn", correspondente ao idioma em que o nome e o endereço do lugar são solicitados. Se nenhum for solicitado, o padrão será inglês.

Identificadores SearchRegionRequestData

OBRIGATÓRIO: address, latlng ou place_id.

Campo Tipo Descrição
address string Um endereço não estruturado dentro de uma região a ser correspondida. É necessário usar o region_code quando o address é especificado.
latlng LatLng A latitude e longitude contidas em uma região a ser correspondida.
place_id string Um ID de lugar que está dentro de uma região a ser correspondida.
place_type tipo de lugar Obrigatório. O tipo de região a ser correspondida.
language_code string O código de idioma BCP-47, como "en-US" ou "sr-Latn", correspondente ao idioma em que o nome e o endereço do lugar são solicitados. Se nenhum for solicitado, o padrão será o inglês.
region_code string Código de país/região ISO-3166 de duas letras do local a ser correspondido. O region_code é obrigatório quando o endereço é especificado.

Tipos de lugar

Valor Descrição
POSTAL_CODE Um código postal, como usado para endereçar correspondências no país.
ADMINISTRATIVE_AREA_LEVEL_1 Uma entidade civil de primeira ordem, abaixo do nível de país. Nos Estados Unidos, esses níveis administrativos são estados.
ADMINISTRATIVE_AREA_LEVEL_2 Uma entidade civil de segunda ordem, abaixo do nível de país. Nos Estados Unidos, esses níveis administrativos são condados.
LOCALITY Uma entidade política incorporada de cidade ou município.
COUNTRY A entidade política nacional, normalmente o tipo de ordem mais alta.

LatLng

Um objeto que representa um par de latitude/longitude. Ele é expresso como um par de valores duplos para representar graus de latitude e longitude. A menos que especificado de outra forma, esse objeto precisa seguir o padrão WGS84. Os valores precisam estar dentro de intervalos normalizados.

Campo Tipo Descrição
latitude dupla A latitude em graus. Precisa estar no intervalo [-90.0, +90.0]. Por exemplo, 47.47583476464538.
longitude dupla A longitude em graus. Precisa estar no intervalo [-180.0, +180.0]. Por exemplo, -121.73858779269906.

Códigos de erro

Valor Descrição
UnknownError Ocorreu um erro desconhecido.
NoMatchFound A solicitação não teve correspondência. Verifique o candidate_place_ids, se disponível.
AddressNotUnderstood Falha na geocodificação do endereço informado.
PlaceTypeMismatch O tipo de local na resposta não corresponde ao da solicitação. Por exemplo, a locality foi solicitada, mas foi retornada a administrative_area_level_2.
MultipleCandidatesFound Correspondência de vários candidatos com a entrada. Verifique o candidate_place_ids, se disponível.
PlaceNameNotUnderstood Falha ao resolver o nome do lugar informado para uma região.
UnitCodeNotFound O código da unidade não foi encontrado. Verifique se o código da unidade é válido e fornecido no formato correto.
PlaceTypeNotAllowed O ID do lugar correspondente não está na lista de permissões do tipo de lugar e país.