<br />

> [!WARNING]
> This product or feature is Experimental (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the [Google
> Maps Platform Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage descriptions](https://developers.google.com/maps/launch-stages.md.txt).

<br />

With the Region Lookup API, you can find the place IDs for
regions, which you can use to style boundary polygons in data-driven styling for boundaries.
The Region Lookup API supports two kinds of requests:

- **Region lookup** looks up a region by place name, [FIPS code](https://transition.fcc.gov/oet/info/maps/census/fips/fips.txt) (U.S. states and counties only), or [ISO-3166-1 country code](https://www.iso.org/obp/ui/#search).
- **Region search** searches for the region that contains a specific location as specified by an address, [`LatLng`](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#latlng), or place ID.

## Supported region place types

The following region place types are supported:
`country`, `administrative_area_level_1`, `administrative_area_level_2`, `postal_code`,
`locality`.

## Install the library

To use the Region Lookup API, take these steps:

1. [Enable Region Lookup API in the console](https://developers.google.com/maps/documentation/javascript/dds-boundaries/start.md.txt).
2. Install the [open source library](https://github.com/googlemaps/js-region-lookup): `npm install @googlemaps/region-lookup`

## Import dependencies from the library

The Region Lookup open source library provides a set of functions and TypeScript
typings that you must import into your code.

- For region lookup requests, import the following:

  ```javascript
  import {
    lookupRegion,
    LookupRegionRequestData,
    LookupRegionResponseData,
    LookupRegionResponse,
    RegionIdentifier
  } from "@googlemaps/region-lookup";
  ```
- For region search requests, import the following:

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

> [!CAUTION]
> **Caution:** The Region Lookup API and open source library for Javascript are [Experimental Releases](https://cloud.google.com/maps-platform/terms/maps-service-terms#9.-pre-ga-offerings).

## Region lookup requests

A region lookup request takes a place name or identifier code, and returns a
place ID. To look up a region, call `lookupRegion()`, specifying a
[`LookupRegionRequestData`](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#lookup-region-request-data) with the following
parameters:

- `place` or `unit_code` (required) Either the region name (`place`) or `unit_code` of the place. `unit_code` can be either a FIPS code (U.S. states and counties only), or ISO-3166-1 country code.
- `place_type` (required) The [place type](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#place-type) value for the type of place to look up.
- `region_code` Two-letter ISO-3166 country/region code for the location to match. `region_code` is optional if place_type is `COUNTRY`.
- `language` The BCP-47 language code, such as "en-US" or "sr-Latn". If none is specified the default is en-US.

The following example shows a lookup request for Newark, NJ.

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

Either the `place` or `unit_code` parameter are required. If none is specified,
an error is returned.

The `region_code` parameter is required unless `place_type` is `COUNTRY`.

`place` and `unit_code` specify a location to match a place ID to. For example
if `place` is "California" and `place_type` is `ADMINISTRATIVE_AREA_LEVEL_1`,
the API returns the place ID for California as the `matched_place_id`:

- `place_type`: `ADMINISTRATIVE_AREA_LEVEL_1`

  `matched_place_id` results: place ID for California. All other
  supported types return no match.

If `unit_code` is "6" (FIPS Code for California), `place_type` is `ADMINISTRATIVE_AREA_LEVEL_1`,
and `region_code` is "US," the API returns the place ID for California:

- `place_type`: `ADMINISTRATIVE_AREA_LEVEL_1`
- `region_code`: `US`

  `matched_place_id` results: place ID for California. All other
  supported types return no match.

If `unit_code` is "US" the API returns the following results when the
following `place_type`s are specified:

- `place_type`: `COUNTRY`

  `matched_place_id` results: place ID for the United States. All other
  supported types return no match.

If no match is found, `matched_place_id` is not set.

Candidate place IDs are returned in the case of ambiguity. For example if `place`
is "Santa Clara County" and `place_type` is `LOCALITY` the place ID for Santa Clara County is
returned as a candidate.

### Region lookup response

The `LookupRegionResponse` object contains a `matched_place_id` if a result was found. If
no result is found, lower confidence place IDs are returned as candidate IDs,
along with an [error code](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#error-codes) containing debugging information.

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

## Region search requests

To find a region that contains a specific location, call `searchRegion`
specifying a [`SearchRegionRequestData`](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#search-region-request-data) with the
following parameters:

- `address` or `latlng` or `place_id` (required) Contains either an unstructured address string, [`latlng`](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#latlng), or [place ID](https://developers.google.com/maps/documentation/javascript/place-id.md.txt) contained by the region (for example POI, building, and so on). If none is specified, an error is returned.
- `place_type` (required) The [place type](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#place-type) value for the type of region to search for.
- `region_code` Two-letter ISO-3166 country/region code for the location to match. `region_code` is required when `address` is specified.
- `language` The BCP-47 language code, such as "en-US" or "sr-Latn". If none is specified the default is en-US.

The following example shows a lookup request for Burbank, CA.

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

### Region search response

The `SearchRegionResponse` object contains a `matched_place_id` if a result was found. In
the case of a failed match the response contains one or more candidate place
IDs and an [error code](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#error-codes).

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

## Reference

### `LookupRegionRequestData` identifiers

| Field | Type | Description |
|---|---|---|
| `place` | string | The name of the region to match to a place ID. Use the `place` field in combination with `place_type` to look up the region place ID. For example if `place_type` is "locality", a valid `place` can be "Palo Alto, CA". If `place_type` is \`POSTAL_CODE\`, a valid place_name can be "94109". If `place_type` is \`COUNTRY\`, a valid `place` can be "United States", etc. `region_code` is required when `place` is specified unless `place_type` is \`COUNTRY\`. |
| `unit_code` | string | The FIPs state or county codes (U.S. only) or ISO-3166-1 country code to be matched. The `unit_code` field is used in combination with `place_type` to look up the region place ID. For example: If `place_type` is `COUNTRY`, a valid unit_code can be "US" (ISO-3166-1 Alpha-2 code for United States) or "BR" (ISO-3166-1 Alpha-2 code for Brazil). If `place_type` is `ADMINISTRATIVE_AREA_LEVEL_1` (state) and region_code is "US", a valid unit_code can be "6" (FIPs code for California) or "12"(FIPs code for Florida). If place_type is `ADMINISTRATIVE_AREA_LEVEL_2` (county) and region_code is "US", a valid unit_code can be "6001" (FIPs code for Alameda County in California) or "12086" (FIPs code for Miami-Dade County in Florida). `region_code` is required when specifying a FIPs code. `region_code` is ignored for ISO-3166-1 country codes. |
| `place_type` | PlaceType | Required. The type of region to match. |
| `region_code` | string | Two-letter ISO-3166 country/region code for the location you're trying to match. region_code is optional if `place_type` is \`COUNTRY\`. |
| `language_code` | string | The BCP-47 language code, such as "en-US" or "sr-Latn", corresponding to the language in which the place name and address is requested. If none is requested, then it defaults to English. |

### `SearchRegionRequestData` identifiers

**REQUIRED:** One of `address`, `latlng`, or `place_id`.

| Field | Type | Description |
|---|---|---|
| `address` | string | An unstructured street address that is contained inside a region to match. `region_code` is required when `address` is specified. |
| `latlng` | [LatLng](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#latlng) | The latitude and longitude that is contained inside a region to match. |
| `place_id` | string | A place ID that is contained inside a region to match. |
| `place_type` | [place type](https://developers.google.com/maps/documentation/javascript/dds-boundaries/region-lookup.md.txt#place-type) | Required. The type of region to match. |
| `language_code` | string | The [BCP-47 language code](https://en.wikipedia.org/wiki/IETF_language_tag), such as "en-US" or "sr-Latn", corresponding to the language in which the place name and address is requested. If none is requested, then it defaults to English. |
| `region_code` | string | Two-letter ISO-3166 country/region code for the location to match. `region_code` is required when address is specified. |

### Place types

| Value | Description |
|---|---|
| `POSTAL_CODE` | A postal code, as used to address postal mail within the country. |
| `ADMINISTRATIVE_AREA_LEVEL_1` | A first-order civil entity below the country level. Within the United States, these administrative levels are states. |
| `ADMINISTRATIVE_AREA_LEVEL_2` | A second-order civil entity below the country level. Within the United States, these administrative levels are counties. |
| `LOCALITY` | An incorporated city or town political entity. |
| `COUNTRY` | The national political entity, typically the highest order type. |

### LatLng

An object that represents a latitude/longitude pair. This is expressed as a
pair of doubles to represent degrees latitude and degrees longitude. Unless
specified otherwise, this object must conform to the [WGS84 standard](https://en.wikipedia.org/wiki/World_Geodetic_System#1984_version).
Values must be within normalized ranges.

| Field | Type | Description |
|---|---|---|
| `latitude` | double | The latitude in degrees. It must be in the range `[-90.0, +90.0]`. For example `47.47583476464538`. |
| `longitude` | double | The longitude in degrees. It must be in the range `[-180.0, +180.0]`. For example `-121.73858779269906`. |

### Error codes

| Value | Description |
|---|---|
| `UnknownError` | An unknown error occurred. |
| `NoMatchFound` | The request resulted in no match, check `candidate_place_ids` if available. |
| `AddressNotUnderstood` | Geocoding failed for the provided address. |
| `PlaceTypeMismatch` | The place type in the response does not match that of the request. For example, `locality` was requested but `administrative_area_level_2` was returned. |
| `MultipleCandidatesFound` | Multiple candidates were matched to the input. Check `candidate_place_ids`. if available. |
| `PlaceNameNotUnderstood` | The place name provided failed to resolve to a region. |
| `UnitCodeNotFound` | Unit code was not found. Verify that the unit code is valid and provided in the correct format. |
| `PlaceTypeNotAllowed` | The matched place ID is not in the allowlist of place type and country. |