Use the Region Lookup API

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. 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, administrative_area_level_3, administrative_area_level_4. postal_code, locality, sublocality_level_1, neighborhood.

Installing the library

To use the Region Lookup API, take these steps:

  1. Enable Region Lookup API in the console.
  2. Install the open source library: npm install @googlemaps/region-lookup

Importing dependencies from the library

The Region Lookup open source library provides a set of functions and TypeScript typings that you will need to 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.
ADMINISTRATIVE_AREA_LEVEL_3 A third-order civil entity below the country level.
ADMINISTRATIVE_AREA_LEVEL_4 A fourth-order civil entity below the country level.
LOCALITY An incorporated city or town political entity.
SUBLOCALITY_LEVEL_1 A first-order civil entity below a locality.
NEIGHBORHOOD A named neighborhood.
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.