Cómo usar la API de Region Lookup

Con la API de Region Lookup, puedes encontrar los IDs de lugar de las regiones y usarlos para definir el estilo de los polígonos de límite en el diseño basado en datos. La API de Region Lookup admite dos tipos de solicitudes:

Búsqueda de región: Busca una región por el nombre de lugar, el código FIPS (solo para estados y condados de EE.UU.) o el código de país ISO-3166-1.
Búsqueda por región: Busca la región que contiene una ubicación en particular según una dirección, LatLng o ID de lugar.

Tipos de lugares admitidos en una región

Se admiten los siguientes tipos de lugares en una región: country, administrative_area_level_1, administrative_area_level_2, postal_code y locality.

Cómo instalar la biblioteca

Para usar la API de Region Lookup, sigue estos pasos:

Habilita la API de Region Lookup en la consola.
Instala la biblioteca de código abierto: npm install @googlemaps/region-lookup.

Cómo importar dependencias desde la biblioteca

La biblioteca de código abierto de Region Lookup proporciona un conjunto de funciones y typings de TypeScript que deberás importar a tu código.

Para las solicitudes de búsqueda de región, importa lo siguiente:

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

Para las solicitudes de búsqueda por región, importa lo siguiente:

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

Solicitudes de búsqueda de región

Una solicitud de búsqueda de región toma un nombre de lugar o un código identificador y muestra un ID de lugar. Para buscar una región, llama a lookupRegion() y especifica un objeto LookupRegionRequestData con los siguientes parámetros:

place o unit_code (obligatorio): Es el nombre de la región (place) o el unit_code del lugar. unit_code: Puede ser un código FIPS (solo para estados y condados de EE.UU.) o un código de país ISO-3166-1.
place_type (obligatorio): Es el valor del tipo de lugar correspondiente al tipo de lugar que se debe buscar.
region_code: Es el código de país o región ISO-3166 de dos letras que debe coincidir con la ubicación. region_code es opcional si place_type es COUNTRY.
language: Es el código de idioma BCP-47, como "en-US" o "sr-Latn". Si no se especifica ninguno, el valor predeterminado es en-US.

En el siguiente ejemplo, se muestra una solicitud de búsqueda para Newark, Nueva Jersey.

// 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 });

Es obligatorio incluir el parámetro place o unit_code. Si no se especifica ninguno, se muestra un error.

El parámetro region_code es obligatorio, a menos que place_type sea COUNTRY.

place y unit_code especifican una ubicación con la que debe coincidir el ID de lugar. Por ejemplo, si place es "California" y place_type es ADMINISTRATIVE_AREA_LEVEL_1, la API muestra el ID de lugar de California como matched_place_id:

place_type: ADMINISTRATIVE_AREA_LEVEL_1

Resultados de matched_place_id: ID de lugar de California. Los demás tipos admitidos no muestran coincidencias.

Si unit_code es "6" (código FIPS de California), place_type es ADMINISTRATIVE_AREA_LEVEL_1 y region_code es "US", la API muestra el ID de lugar de California:

place_type: ADMINISTRATIVE_AREA_LEVEL_1
region_code: US

Resultados de matched_place_id: ID de lugar de California. Los demás tipos admitidos no muestran coincidencias.

Si unit_code es "US", la API muestra los siguientes resultados cuando se especifican los siguientes place_type:

place_type: COUNTRY

Resultados de matched_place_id: ID de lugar de Estados Unidos. Los demás tipos admitidos no muestran coincidencias.

Si no se encuentra ninguna coincidencia, no se establece el matched_place_id.

En caso de ambigüedad, se muestran los IDs de lugar de los candidatos. Por ejemplo, si place es "Condado de Santa Clara" y place_type es LOCALITY, se muestra el ID de lugar del condado de Santa Clara como candidato.

Respuesta de búsqueda de región

El objeto LookupRegionResponse contiene un matched_place_id si se encuentra un resultado. Si no se encuentra ningún resultado, los IDs de lugar de menor confianza se muestran como IDs candidatos, junto con un código de error que contiene información de depuración.

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

Solicitudes de búsqueda por región

Para buscar una región que contenga una ubicación específica, llama a searchRegion y especifica un SearchRegionRequestData con los siguientes parámetros:

address, latlng o place_id (obligatorio): Contiene una string de dirección no estructurada, un objeto latlng o un ID de lugar que se encuentra en la región (por ejemplo, lugares de interés, edificios, etc.). Si no se especifica ninguno, se muestra un error.
place_type (obligatorio): Es el valor del tipo de lugar correspondiente al tipo de región que se debe buscar.
region_code: Es el código de país o región ISO-3166 de dos letras que debe coincidir con la ubicación. region_code es obligatorio cuando se especifica address.
language: Es el código de idioma BCP-47, como "en-US" o "sr-Latn". Si no se especifica ninguno, el valor predeterminado es en-US.

En el siguiente ejemplo, se muestra una solicitud de búsqueda de Burbank, California.

// 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 });

Respuesta de búsqueda por región

El objeto SearchRegionResponse contiene un matched_place_id si se encuentra un resultado. En el caso de que no haya coincidencias, la respuesta contiene uno o más IDs de lugar que son candidatos y un código de error.

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

Referencia

Identificadores de `LookupRegionRequestData`

Campo	Tipo	Descripción
`place`	string	Es el nombre de la región que debe coincidir con el ID de lugar. Usa el campo `place` junto con `place_type` para buscar el ID de lugar de la región. Por ejemplo, si el `place_type` es "localidad", un `place` válido puede ser "Palo Alto, California". Si el `place_type` es "POSTAL_CODE", un valor válido para place_name puede ser "94109". Si el `place_type` es "COUNTRY", un `place` válido puede ser "Estados Unidos", etc. Se requiere `region_code` cuando se especifica `place`, a menos que `place_type` sea "COUNTRY".
`unit_code`	string	Corresponde a los códigos FIPS de estados o condados (solo en EE.UU.) o al código de país ISO-3166-1 con los que debe coincidir. Se usa el campo `unit_code` junto con `place_type` para buscar el ID de lugar de la región. Por ejemplo: si el `place_type` es `COUNTRY`, un unit_code válido puede ser "US" (código ISO-3166-1 alfa-2 para Estados Unidos) o "BR" (código ISO-3166-1 alfa-2 para Brasil). Si el `place_type` es `ADMINISTRATIVE_AREA_LEVEL_1` (estado) y el region_code es "US", un unit_code válido puede ser "6" (código FIPS para California) o "12" (código FIPS para Florida). Si place_type es `ADMINISTRATIVE_AREA_LEVEL_2` (condado) y region_code es "US", un campo unit_code válido puede ser "6001" (código FIPS para el condado de Alameda en California) o "12086" (código FIPS para el condado de Miami-Dade en Florida). `region_code` es obligatorio cuando se especifica un código FIPS. `region_code` se ignora para los códigos de país ISO-3166-1.
`place_type`	PlaceType	Este campo es obligatorio. Es el tipo de región con el que se buscarán coincidencias.
`region_code`	string	Es el código de país o región ISO-3166 de dos letras de la ubicación para la que buscas coincidencias. region_code es opcional si el `place_type` es "COUNTRY".
`language_code`	string	Es el código de idioma BCP-47, como "en-US" o "sr-Latn", que corresponde al idioma en el que se solicitan el nombre y la dirección del lugar. Si no se solicita ninguno, el valor predeterminado es inglés.

Identificadores de `SearchRegionRequestData`

OBLIGATORIO: Puede ser address, latlng o place_id.

Campo	Tipo	Descripción
`address`	string	Es una dirección no estructurada que se encuentra en una región con la que debe coincidir. `region_code` es obligatorio cuando se especifica `address`.
`latlng`	LatLng	Indica la latitud y la longitud que se encuentran en una región con la que deben coincidir.
`place_id`	string	Es un ID de lugar que se encuentra en una región con la que debe coincidir.
`place_type`	tipo de lugar	Este campo es obligatorio. Es el tipo de región con el que se buscarán coincidencias.
`language_code`	string	Es el código de idioma BCP-47, como "en-US" o "sr-Latn", que corresponde al idioma en el que se solicitan el nombre y la dirección del lugar. Si no se solicita ninguno, el valor predeterminado es inglés.
`region_code`	string	Es el código de país o región ISO-3166 de dos letras que debe coincidir con la ubicación. `region_code` es obligatorio cuando se especifica la dirección.

Tipos de lugares

Valor	Descripción
`POSTAL_CODE`	Indica un código postal, tal como se usa en las direcciones postales dentro del país.
`ADMINISTRATIVE_AREA_LEVEL_1`	Indica una entidad civil de primer rango por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los estados.
`ADMINISTRATIVE_AREA_LEVEL_2`	Indica una entidad civil de segundo rango por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los condados.
`LOCALITY`	Indica una entidad política integrada en una ciudad o un pueblo.
`COUNTRY`	Indica la entidad política nacional y suele ser el tipo de rango más alto.

LatLng

Es un objeto que representa un par de valores de latitud y longitud. Se expresa como un par de dobles para representar la latitud y la longitud en grados. A menos que se especifique lo contrario, este objeto debe cumplir con el estándar WGS84. Los valores deben pertenecer a rangos normalizados.

Campo	Tipo	Descripción
`latitude`	doble	Es la latitud expresada en grados. Debe pertenecer al rango `[-90.0, +90.0]`. Por ejemplo, `47.47583476464538`.
`longitude`	doble	Es la longitud expresada en grados. Debe pertenecer al rango `[-180.0, +180.0]`. Por ejemplo, `-121.73858779269906`.

Códigos de error

Valor	Descripción
`UnknownError`	Se produjo un error desconocido.
`NoMatchFound`	La solicitud no arrojó ninguna coincidencia. Consulta los `candidate_place_ids`, si corresponde.
`AddressNotUnderstood`	Falló la geocodificación para la dirección proporcionada.
`PlaceTypeMismatch`	El tipo de lugar de la respuesta no coincide con el de la solicitud. Por ejemplo, se solicitó `locality`, pero se mostró `administrative_area_level_2`.
`MultipleCandidatesFound`	Varios candidatos coinciden con la entrada. Consulta `candidate_place_ids`, si corresponde.
`PlaceNameNotUnderstood`	No se pudo encontrar una región para el nombre de lugar proporcionado.
`UnitCodeNotFound`	No se encontró el código de unidad. Verifica que el código de unidad sea válido y se haya proporcionado en el formato correcto.
`PlaceTypeNotAllowed`	El ID de lugar encontrado no forma parte de la lista de entidades permitidas de tipo de lugar y país.