Guides

Geocode Lookups

Look up geolocation reference data with Location Intelligence

Overview

A geocode lookup is a Location Intelligence data product that enables you to query ("look up") geolocation data stored in RMS reference tables. Geolocation data is reference data that identifies a location at a particular resolution level. This geolocation data plays a key role in geocoding workflows.

Geocoding is the process of estimating the global coordinates of a location (its latitude and longitude) based on known geolocation data, such as an address, postal code, or country. The accuracy of global coordinates returned during geocoding depends on the quality of the geolocation data provided in the geocoding request.

Geocode lookups enable you to access reference data at different resolution levels so that you can identify location exposures with greater accuracy and provide the geocoding engine with higher quality reference data. Generally, this data is provided in the form of geographic identifier values that identify a location at a particular resolution level. For example, admin2Code, admin2Name, andadmin2GeoId values may be used to identify a particular location at the admin2 resolution level.

Data products

Location Intelligence enables you to look up geolocation reference data by data product and data version. Each data product is exposed via a unique endpoint that enables you to look up reference data at a particular resolution level. Country geocode lookups provide access to reference data at the country resolution level (i.e. country-level data).

Geocode lookup endpoints follow two patterns:

  • Look up by query. These endpoints enable you to append query parameters to an endpoint path an retrieve all reference data matching the specified parameters. The data product and data version are defined in the path: /li/geocode/<version>/<resolution>. For example, the li/geocode/20.0/country endpoint returns country-level reference data using version 20.0 data. For more information on query parameters in geocode lookups, see Filter reference data.
  • Look up by ID. These endpoints enable you specify the ID number of a particular geolocation. The data product, data version, and gelocation ID are specified in the path: /li/geocode/<version>/<resolution>/{id}. For example, the li/geocode/20.0/country/840 endpoint returns country-level reference data for the United States (countryGeoId = 840) using version 20.0 data. For more information on query parameters in geocode lookups, see Look up reference data by ID.

Resolution levels

Each geocode lookup data product represents a particular resolution level and provides access to geolocation reference data at that level.

Accuracy and confidence in modeled results are driven by the quality of geolocation reference data provided to the gelocation engine. As geocoding resolution increases, the number of assumptions made during the modeling process decreases and the more accurate the global coordinates returned during gelocation.

The table orders data products by resolution level. Lower resolutions are presented at the top of the table:

Data ProductGeoResolutionCodeGeographic identifiersVersions
country14countryIso2a, countryFips, countryRmsCode, countryName18.0, 18.1, 20.0, 21.0, 22.0
zone111zone1Name zone1GeoId18.0, 18.1, 20.0, 21.0, 22.0
zone311zone3Name zone3GeoId18.0, 18.1, 20.0, 21.0, 22.0
zone411zone4Name zone4GeoId18.0, 18.1, 20.0, 21.0, 22.0
admin110admin1Code, admin1Name, admin1GeoId18.0, 18.1, 20.0, 21.0, 22.0
admin29admin2Code, admin2Name, admin2GeoId18.0, 18.1, 20.0, 21.0, 22.0
admin38admin3Code, admin3Name, admin3GeoId18.0, 18.1, 20.0, 21.0, 22.0
city7cityCode, cityName, cityGeoId18.0, 18.1, 20.0, 21.0, 22.0
admin46admin4Code, admin4Name, admin4GeoId18.0, 18.1, 20.0, 21.0, 22.0
postalCode5postalCodeGeoId, postalCode18.0, 18.1, 20.0, 21.0, 22.0
locationCode5locationCode, locationCodeGeoId18.0, 18.1, 20.0, 21.0, 22.0

Data versions

Location Intelligence offers multiple versions of each reference table. Data products are available in the following versions: 18.0, 18.1, 20.0, 21.0, and 22.0.

The latest endpoint always retrieves the most recent RMS data. For example, requests using the li/geocode/latest/country/{id} endpoint return country-level geolocation data from the latest version of the Geocode Country reference table. The latest version is currently 22.0.

Look up admin1 data

The Admin1 resolution level (GeoResolutionCode 10) represents large geographic divisions such as states, provinces, and regions within countries.

The admin1 Latest resource (GET /geocode/latest/admin1) returns admin1-level geolocation data from the latest reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

This resource enables you to filter reference data using the admin1Code and admin1Name attribute values as query parameters. You can also specify sort, limit, andoffset query parameters to manage the data returned:

curl --request GET \
     --url 'https://{host}/li/geocode/latest/admin1?admin1Code=CA&limit=100&offset=0' \
     --header 'Accept: application/json'

Both resources return country-level and admin1-level geolocation data: 

[
  {
    "countryIso2a": "US",
    "countryFips": "US",
    "countryRmsCode": "US",
    "countryName": "United States",
    "countryGeoId": 840,
    "admin1Code": "CA",
    "admin1Name": "CALIFORNIA",
    "admin1GeoId": 99999106
  }
]

Look up admin2 data

The Admin2 administrative division (GeoResolutionCode 9) is a category of reference data that represents small geographic divisions (for example, counties) within Admin1 administrative divisions (for example, states).

The admin2 Latest resource (GET /geocode/latest/admin2) returns admin3-level geolocation data from the latest version of the Geocode Admin 2 reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

The resource enables you to search for reference data using admin2Code and admin2Name attribute values as query parameters. The countryFips and admin1Code query parameters are also supported.

curl --request GET \
     --url 'https://{host}/li/geocode/latest/admin2?admin2Code=001&limit=100&offset=0' \
     --header 'Accept: application/json'

The resource returns country-level, admin1-level, and admin2-level geolocation data: 

[
  {
    "countryIso2a": "US",
    "countryFips": "US",
    "countryRmsCode": "US",
    "countryName": "United States",
    "countryGeoId": 840,
    "admin1Code": "CA",
    "admin1Name": "CALIFORNIA",
    "admin1GeoId": 99999106,
    "admin2Code": "001",
    "admin2Name": "ALAMEDA COUNTY",
    "admin2GeoId": 99999206001
  }
]

Look up admin3 data

The Admin3 administrative division (GeoResolutionCode 8) is a category of reference data that represents small geographic divisions (for example, municipalities) within admin2 administrative divisions (for example, counties).

The admin3 Latest resource (GET /geocode/latest/admin3) returns admin3-level geolocation data from the latest version of the Geocode Admin 3 reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

The resource enables you to search for reference data using admin3Code and admin3Name attribute values as query parameters. Other country-level, admin1-level, and admin3-level query parameters are also supported. 

curl --request GET \
     --url 'https://{host}/li/geocode/latest/admin3?countryFips=AE&limit=100&offset=0' \
     --header 'Accept: application/json'

The resource returns country-level, admin1-level, admin2-level, and admin3-level reference data: 

[
  {
    "countryIso2a": "AE",
    "countryFips": "AE",
    "countryRmsCode": "AE",
    "countryName": "United Arab Emirates",
    "countryGeoId": 784,
    "admin1Code": "",
    "admin1Name": "Dubai",
    "admin1GeoId": 2347111,
    "admin2Code": "",
    "admin2Name": "Dubai",
    "admin2GeoId": 61762805,
    "admin3Code": "",
    "admin3Name": "Umm Suqeim Second",
    "admin3GeoId": 61762880
  }
]

Look up admin4 data

The admin4 administrative division is a category of reference data that represents small geographic divisions (for example, districts or neighborhoods) within admin3 administrative divisions (for example, municipalities).

The admin4 Latest resource (GET /geocode/latest/admin4) returns geolocation data from the latest version of the Geocode Admin 4 reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

The resource enables you to search for reference data using anadmin4Name attribute value as a query parameter:

curl --request GET \
     --url 'https://api-euw1.rms.com/li/geocode/latest/admin4?admin4Name=Lima%20San%20Isidro%20CBD&limit=100&offset=0' \
     --header 'Accept: application/json'

The resource returns country-level, admin1-level, admin2-level, and admin4-level reference data: 

[
  {
    "countryIso2a": "PE",
    "countryFips": "PE",
    "countryRmsCode": "PE",
    "countryName": "Peru",
    "countryGeoId": 604,
    "admin1Code": "15",
    "admin1Name": "Lima",
    "admin1GeoId": 2346482,
    "admin2Code": "1501",
    "admin2Name": "Lima",
    "admin2GeoId": 64079965,
    "cityCode": "335570",
    "cityName": "Lima CBD",
    "cityGeoId": 30335570,
    "admin4Code": "71043",
    "admin4Name": "Lima San Isidro CBD",
    "admin4GeoId": 71071043
  }
]

Look up city data

A city is a category of reference data (GeoResolutionCode 7) that identifies a city or town.

The city Latest resource (GET /geocode/latest/city) returns city-level geolocation data from the latest version of the Geocode City reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

The resource enables you to search for reference data using cityCode and cityName attribute values as query parameters:

curl --request GET \
     --url 'https://{host}/li/geocode/latest/city?cityCode=282001&limit=100&offset=0' \
     --header 'Accept: application/json'

The resource returns country-level, admin1-level, admin2-level, admin3-level, and city-level data: 

[
  {
    "countryIso2a": "AG",
    "countryFips": "AC",
    "countryRmsCode": "CB",
    "countryName": "Antigua and Barbuda",
    "countryGeoId": 28,
    "admin1Code": "200",
    "admin1Name": "Barbuda",
    "admin1GeoId": 60375118,
    "admin2Code": "200",
    "admin2Name": "Barbuda",
    "admin2GeoId": 2344541,
    "admin3Code": "28200001",
    "admin3Name": "AG001",
    "admin3GeoId": 60372390,
    "cityCode": "282001",
    "cityName": "The Caves",
    "cityGeoId": 56228
  }
]

Look up country data

A country is a category of reference data (GeoResolutionCode 14) that identifies a country or nation.

The country Latest resource (GET /geocode/latest/country) returns country-level reference data from the latest version of the Geocode Country reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

The resource enables you to search for reference data using countryFips and countryName attribute attribute values as query parameters:

curl --request GET \
     --url 'https://{host}/li/geocode/latest/country?countryFips=US&limit=100&offset=0' \
     --header 'Accept: application/json'

The resource returns country-level geolocation data: 

[
  {
    "countryIso2a": "US",
    "countryFips": "US",
    "countryRmsCode": "US",
    "countryName": "United States",
    "countryGeoId": 840
  }
]

Look up locationCode data

The Location Code division is a category of reference data that identifies a postal code area in the United Kingdom.

The locationCode Latest resource (GET /geocode/latest/locationCode) returns geolocation data from the latest version of the Geocode Location Code reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

The resource enables you to search for reference data using a locationCode value as a query parameter. Other country-level, admin1-level, and admin3-level query parameters are also supported. 

curl --request GET \
     --url 'https://{host}/li/geocode/latest/locationCode?locationCode=B62%202&limit=100&offset=0' \
     --header 'Accept: application/json'

The resource returns country-level, admin1-level, admin2-level, admin3-level, city-level, and location-code data: 

[
  {
    "countryIso2a": "GB",
    "countryFips": "UK",
    "countryRmsCode": "GB",
    "countryName": "United Kingdom",
    "countryGeoId": 826,
    "admin1Code": "103",
    "admin1Name": "England",
    "admin1GeoId": 24554868,
    "admin2Code": "103",
    "admin2Name": "Dudley",
    "admin2GeoId": 30277299,
    "admin3Code": "E07CR0",
    "admin3Name": "Dudley",
    "admin3GeoId": 12695865,
    "cityName": "Halesowen",
    "cityGeoId": 22165,
    "locationCode": "B62 2",
    "locationCodeGeoId": 60550885
  }
]

Look up postalCode data

The Postal Code resolution level (geoResolutionCode 14) identifies a postal code area in the United States.

The postalCode Latest resource (GET /geocode/latest/postalcode) returns geolocation data from the latest version of the Geocode Postal Code reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

The resource enables you to search for reference data using a postalCode value as a query parameter. Other country-level, admin1-level, and admin3-level query parameters are also supported. If no query parameter is specified, the resource returns postcode-level reference data for all countries.

curl --location --request GET 'https://{host}/li/geocode/latest/postalCode?countryFips=US' \
--header 'Content-Type: application/json' \
--header 'Authorization: XXXXXXXXXXX' \
--data-raw ''

The resource returns country-level, admin1-level, admin2-level, admin3-level, city-level, and postal-code data: 

[
  {
    "countryIso2a": "US",
    "countryFips": "US",
    "countryRmsCode": "US",
    "countryName": "United States",
    "countryGeoId": 840,
    "admin1Code": "CA",
    "admin1Name": "CALIFORNIA",
    "admin1GeoId": 99999106,
    "admin2Code": "001",
    "admin2Name": "ALAMEDA COUNTY",
    "admin2GeoId": 99999206001,
    "admin3Code": "NE1",
    "admin3Name": "",
    "admin3GeoId": 12695859,
    "cityName": "NEWARK",
    "cityGeoId": 999993061080,
    "postalCode": "94560",
    "postalCodeGeoId": 99999494560
  }
]

Look up zone1 data

The Zone 1 division is a category of reference data (geoResolutionCode 14) identifies a CRESTA zone.

The resource enables you to search for reference data using a zone1Name value as a query parameter. The countryFips query parameter is also supported. 

curl --request GET \
     --url 'https://{host}/li/geocode/latest/zone1?zone1Name=3&limit=100&offset=0' \
     --header 'Accept: application/json'

The resource returns country-level and zone1-level geolocation data: 

[
  {
    "countryIso2a": "DK",
    "countryFips": "DA",
    "countryRmsCode": "DK",
    "countryName": "Denmark",
    "countryGeoId": 208,
    "zone1Name": "3",
    "zone1GeoId": 60344626
  }
]

Look up zone3 data

The Zone 3 resolution level (geoResolutionCode 14) identifies a low-resolution CRESTA zone.

The zone3 Latest resource (GET /geocode/latest/zone3) returns geolocation data from the latest version of the Geocode Zone 3 Code reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

The resource enables you to search for reference data using a zone3Name value as a query parameter. The countryFips query parameter is also supported. 

curl --request GET \
     --url 'https://{host}/li/geocode/latest/zone3?zone3Name=JPN_04&limit=100&offset=0' \
     --header 'Accept: application/json'

The resource returns country-level and zone3-level geolocation data: 

[
  {
    "countryIso2a": "JP",
    "countryFips": "JA",
    "countryRmsCode": "JP",
    "countryName": "Japan",
    "countryGeoId": 392,
    "zone3Name": "JPN_04",
    "zone3GeoId": 64021802
  }
]

Look up zone4 data

The Zone 4 resolution level (geoResolutionCode 14) identifies a high-resolution CRESTA zone.

The zone4 Latest resource (GET /geocode/latest/zone4) returns geolocation data from the latest version of the Geocode Zone 4 Code reference table. Endpoints that specify versions 18.0, 18.1, 20.0, 21.0, and 22.0 of the data product are also supported.

The resource enables you to search for reference data using a zone4Name value as a query parameter. The countryFips query parameter is also supported. 

curl --request GET \
     --url 'https://{host}/li/geocode/latest/zone4?countryFips=EZ&zone4Name=CZE_68742&limit=100&offset=0' \
     --header 'Accept: application/json'

The resource returns country-level and zone4-level geolocation data: 

[
  {
    "countryIso2a": "CZ",
    "countryFips": "EZ",
    "countryRmsCode": "CZ",
    "countryName": "Czech Republic",
    "countryGeoId": 203,
    "zone4Name": "CZE_68742",
    "zone4GeoId": 64048047
  }
]

Look up reference data by ID

Location Intelligence enables you to look up reference data for particular geolocations by specifying the location's geographic ID in the endpoint path.

A geographic ID is a unique ID number that identifies a location at a particular resolution level (e.g. countryGeoId, admin1GeoId, admin2GeoId). Each data product accepts the appropriate geographic ID for that resolution level.

The data product, data version, and geographic ID are specified in the path: /li/geocode///{id}. For example, if you want admin1-level reference data for a particular location, use the admin1 by ID Latest resource (GET /geocode/latest/admin1/{id}) and specify an admin1GeoId value in the endpoint path: 

curl --request GET \
     --url 'https://{host}/li/geocode/latest/admin1/99999106' \
     --header 'Accept: application/json'

Filter reference data

Geocode lookup data products support the use query parameters to filter, sort, and paginate the data returned from a reference table.

The query string parameter is appended to the resource endpoint using the ? character enabling you to define the scope of the query. For example, if you are only interested in viewing admin1-level reference data for locations within the United States, you could specify a countryFips query parameter in the request: 

curl --request GET \
     --url 'https://{host}/li/geocode/latest/admin1?countryFips=US&limit=100&offset=0' \
     --header 'Accept: application/json'

Geocode lookups support four basic query string parameters: attribute queries, sort, limit, and offset.

GET /resource-path

?

[ attribute [ = | != | > | < | LIKE | NOT LIKE ] attribute-value ]

[ sort= attribute= ASC | DESC ]

[ limit= number]

[ offset= number]

Every query string parameter is defined by a parameter keyword, a query string, and a comparison operator (=) that connects the parameter keyword to the query string. You can use the & operator to append multiple query string parameters to the endpoint.

  • An attribute value filter selects the data returned from the reference table. Each data product supports query parameters that are appropriate at that level. In general, a data product will support query parameters representing levels above it in the hierarchy. For example, the admin3data products enable you to filter results using country-level, admin1-level, and admin2-level query parameters.
  • A sort query string parameter specifies an attribute on which to sort and the sort order (alphabetical or numerical) for the records returned from the resource. One of ASC for ascending or DESC for descending.
  • A limit query string parameter specifies the number of records to display per page. By default, 100.
  • An offset query string parameter specifies the number of pages that are offset before the initial page of records returned. By default, 0.

More information

Support Center is a password-protected area for licensees of RMS catastrophe modeling products. It includes a library of technical software documentation and model documentation for RMS peril models.

For information about how geocoding works within RMS software, see Understanding Geocoding in RMS Applications on Moody's RMS Support Center.

Updated about 1 year ago