Pronto habrá nuevas opciones para el diseño de mapas disponibles en Google Maps Platform. Esta actualización del diseño de mapas incluye una nueva paleta de colores predeterminada, así como mejoras en la experiencia y la usabilidad del mapa. Todos los diseños de mapa se actualizarán automáticamente en marzo de 2025. Para obtener más información sobre la disponibilidad y cómo habilitar esta actualización antes, consulta Nuevo diseño de mapa para Google Maps Platform.

Utiliza la API de Region Lookup

Con la API de Region Lookup, puedes encontrar los IDs de lugar de regiones y usarlos para definir los polígonos de límites con un diseño basado en datos aplicable a límites. La API de Region Lookup admite dos tipos de solicitudes:

Consulta de región por nombre o código: Busca una región por nombre de lugar, código del FIPS (estados y condados de EE.UU. únicamente) o código de país según la norma ISO-3166-1.
Búsqueda de región por ubicación: Busca la región que contiene una ubicación específica que se indica con su dirección, LatLng o ID de lugar.

Tipos de lugares admitidos en una región

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

Cómo instalar la biblioteca

Para utilizar 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 utilizada en Region Lookup incluye un conjunto de funciones y definiciones de TypeScript que debes importar en tu código.

Para las solicitudes de consulta de región por nombre o código, importa lo siguiente:

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

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

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

Solicitudes de consulta de región por nombre o código

Una solicitud de consulta de región por nombre o código toma un nombre de lugar o un código identificador para mostrar un ID de lugar. Para buscar una región, llama a lookupRegion() especificando 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 del FIPS (estados y condados de EE.UU. únicamente) o un código de país según la norma ISO-3166-1.
place_type (obligatorio): Es el valor del tipo de lugar que se debe buscar.
region_code: Es el código de país/región de dos letras, según la norma ISO-3166, que tiene que coincidir con la ubicación. region_code es opcional si place_type es COUNTRY.
language: Es el código de idioma según la norma BCP-47, como "en-US" o "sr-Latn". Si no se especifica ninguno, la configuración predeterminada es en-US.

En el siguiente ejemplo se muestra una solicitud de consulta 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 uno de los parámetros place o unit_code. Si no se especifica ninguno, se mostrará 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 de California según el FIPS), 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" y se especifican los siguientes place_type, la API muestra estos resultados:

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 una coincidencia, no se establecerá ningún matched_place_id.

En caso de ambigüedad, se muestran los IDs de lugar de candidatos posibles. 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 consulta de región por nombre o código

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 de región por ubicación

Para encontrar una región que contiene una ubicación específica, llama a searchRegion especificando un objeto SearchRegionRequestData con los siguientes parámetros:

address, latlng o place_id (obligatorio): Contiene una cadena de dirección no estructurada, latlng o ID de lugar que corresponde a la región (por ejemplo, un lugar de interés, un edificio, etc.). Si no se especifica ninguno, se mostrará 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/región de dos letras, según la norma ISO-3166, que tiene que coincidir con la ubicación. region_code es obligatorio cuando se especifica address.
language: Es el código de idioma según la norma BCP-47, como "en-US" o "sr-Latn". Si no se especifica ninguno, la configuración predeterminada es en-US.

En el siguiente ejemplo se muestra una solicitud de consulta por nombre o código para 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 de región por ubicació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`	cadena	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 `place_type` es "locality", un `place` válido puede ser "Palo Alto, California". Si `place_type` es "POSTAL_CODE", un valor válido de place_name puede ser "94109". Si `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`	cadena	Corresponde a un código de estado o condado según el FIPS (solo para EE.UU.) o a un código de país según la norma ISO-3166-1 con el 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 `place_type` es `COUNTRY`, un unit_code válido puede ser "US" (código alfa-2 de Estados Unidos) o "BR" (código alfa-2 de Brasil), según la norma ISO-3166-1. Si `place_type` es `ADMINISTRATIVE_AREA_LEVEL_1` (estado) y region_code es "US", un unit_code válido puede ser "6" (código de California) o "12" (código de Florida), según el FIPS. Si place_type es `ADMINISTRATIVE_AREA_LEVEL_2` (condado) y region_code es "US", un unit_code válido puede ser "6001" (código del condado de Alameda en California) o "12086" (código del condado de Miami-Dade en Florida), según el FIPS. `region_code` es obligatorio cuando se especifica un código del FIPS. `region_code` se ignora para los códigos de país de la norma ISO-3166-1.
`place_type`	PlaceType	Es obligatorio. Corresponde al tipo de región con el que se buscarán coincidencias.
`region_code`	cadena	Es el código de país/región de dos letras, según la norma ISO-3166, que tiene que coincidir con la ubicación indicada en la búsqueda. region_code es opcional si `place_type` es "COUNTRY".
`language_code`	cadena	Es el código de idioma según la norma 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 el inglés.

Identificadores de `SearchRegionRequestData`

OBLIGATORIO: Utiliza address, latlng o place_id.

Campo	Tipo	Descripción
`address`	cadena	Es una dirección no estructurada que se encuentra en una región con la que se debe establecer la coincidencia. `region_code` es obligatorio cuando se especifica `address`.
`latlng`	LatLng	Es la latitud y la longitud que se encuentran dentro de una región con la que se debe establecer la coincidencia.
`place_id`	cadena	Es un ID de lugar que está dentro de una región con la que se debe establecer la coincidencia.
`place_type`	tipo de lugar	Es obligatorio. Corresponde al tipo de región con el que se buscarán coincidencias.
`language_code`	cadena	Es el código de idioma según la norma 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 el inglés.
`region_code`	cadena	Es el código de país/región de dos letras, según la norma ISO-3166, que tiene que 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 para identificar una dirección de correo postal dentro del país.
`ADMINISTRATIVE_AREA_LEVEL_1`	Indica una entidad pública de primer orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los estados.
`ADMINISTRATIVE_AREA_LEVEL_2`	Indica una entidad pública de segundo orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los condados.
`LOCALITY`	Indica una entidad política constituida como ciudad o pueblo.
`COUNTRY`	Indica la entidad política nacional, que suele ser el tipo de orden más alto.

LatLng

Es un objeto que representa un par de valores de latitud y longitud. Esto se expresa como un par de dobles para representar la latitud en grados 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 generó ninguna coincidencia. Verifica `candidate_place_ids`, si está disponible.
`AddressNotUnderstood`	No se pudo ejecutar la geocodificación para la dirección proporcionada.
`PlaceTypeMismatch`	El tipo de lugar incluido en la respuesta no coincide con el de la solicitud. Por ejemplo, se solicitó `locality`, pero se mostró `administrative_area_level_2`.
`MultipleCandidatesFound`	Se encontraron coincidencias de varios candidatos para la entrada. Verifica `candidate_place_ids` si está disponible.
`PlaceNameNotUnderstood`	No se encontraron regiones 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 esté indicado en el formato correcto.
`PlaceTypeNotAllowed`	El ID de lugar que generó una coincidencia no forma parte de la lista de entidades permitidas de tipo de lugar y país.