Places UI Kit: A ready-to-use library that provides room for customization and low-code development. Try it out, and share your input on your UI Kit experience.

Use the Region Lookup API

AI-generated Key Takeaways

The Region Lookup API, currently in Experimental phase, enables identifying region place IDs for styling boundaries in data-driven styling.
It offers two functionalities: region lookup (by name, FIPS/ISO codes) and region search (by address, LatLng, or place ID).
Supported region place types include country, administrative area levels 1 & 2, postal code, and locality.
To utilize the API, enable it in the console and install the open-source library using npm install @googlemaps/region-lookup.
Responses provide matched place IDs or, in cases of ambiguity, candidate IDs and error codes for debugging.

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 (U.S. states and counties only), or ISO-3166-1 country code.
Region search searches for the region that contains a specific location as specified by an address, 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:

Enable Region Lookup API in the console.
Install the open source library: 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:

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

For region search requests, import the following:

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

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 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 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.

// 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_types 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 containing debugging information.

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

Region search requests

To find a region that contains a specific location, call searchRegion specifying a SearchRegionRequestData with the following parameters:

address or latlng or place_id (required) Contains either an unstructured address string, latlng, or place ID 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 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.

// 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.

{
  "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	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	Required. The type of region to match.
`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.
`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. 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.