Overview

The Bulk Geohaz API supports operations for geocoding exposures in bulk.

Geocoding is the process of enriching a location exposure with geolocation data that precisely identifies the global coordinates of a site. Geocoding is a prerequisite for all catastrophe modelling processes.

This API enables client application to geocode large volumes of exposures before those exposures are imported into the Intelligent Risk Platform.

📷

Note

The current version of the the Bulk Geohazard API supports bulk geocoding workflows only. Bulk lookups of hazard data is not currently supported. Future versions of this API will support bulk lookups of hazard data.

Operations

The Bulk Geohaz API exposes the following operations:

Entitlements

Client must be assigned one of the following entitlements to use this API:

• RI-RISKMODELER
• RI-UNDERWRITEIQ

Layers

A layer (data product) is a data asset that is designed to provide actionable insights with minimal overhead and latency.

In its current implementation, the Bulk Geohaz API supports Geocode layers only.

Every Bulk Geohaz job is defined by a list of layers, which specify the data product used to geocode the exposures uploaded to a bulk geohaz folder. Each layer in the request is defined by its name, version, and a list of layer-specific options.

In the current implementation, the API supports layer options that are relevant to geocoding workflows, e.g. aggregateTrigger, forceCountryLevel, licenseType, skipPrevGeocoded.

Geocode Layers

Geocoding is the process of enriching a location exposure with geolocation data that precisely identifies the global coordinates of a site. Geocoding is a prerequisite for all catastrophe modelling processes.

"Geocoding is the process of estimating the global coordinates (latitude and longitude) of a location based on its street address, city, postal code, or other address information. Geocoding software evaluates the address information for completeness and quality using specialized pattern matching algorithms, heuristics, and geographic databases." CHECK THIS? ORIGINAL? For details, see Understanding Geocoding in RMS Applications in Help Center.

The table lists the Geocode layers supported by the Bulk Geocode API:

Beginning with Geocode 23.0, the same data product may be used to geocode portfolios, accounts, and locations in both DLM and HD catastrophe modelling workflows. In the Bulk Geohaz API these model types are identified by license type: DLM (0) and HD (1).

Versions 23.0, 24.0, and 25.0 of the Geocode layer can be used for all exposures using the Moody's geocoding engine, which is identified as 0 in the Bulk Geocode API.

Prior versions of the Geocode layer are available in distinct DLM and HD versions. These versions of the Geocode layer require distinct geocoding engines:

• DLM Geocode layers: Versions 18.0, 18.1, 21.0, and 22.0 of the DLM Geocode layer use the RiskLink (0) geocoding engine.
• HD Geocode layers: Versions 18.1, 21.0, and 22.0 of the 1 of the HD Geocode layer use the Location Intelligence (1) geocoding engine.

Hazard Layers

The current version of the the Bulk Geohazard API does not support bulk lookups of hazard data.

Workflows

The Bulk Geohaz API currently only supports geocoding workflows. Future versions of the Geohaz API will also support bulk lookups of hazard data.

Geocoding Workflows

The Bulk Geohaz API supports workflows for geocoding of large volumes of location exposures. This workflow leverages Amazon S3 APIs to manage the uploading of exposure data to AWS.

The workflow consists of five steps:

1. Prepare a flat file of location exposure data
2. Create a BULK_GEOHAZ folder on AWS S3
3. Upload the flat file of location exposure data to the folder
4. Initiate a BULK_GEOHAZ job to geocode the uploaded location exposure data.
5. Download geocoding results

Step 1: Prepare flat file of exposure data

Create a flat file of location exposure data.

This file is two-dimensional database of data.

• Each row of text defines a location record. The first row in the file is known as the column header; it identifies the properties specified for each location in each subsequent row.
• Each text-delimited column of data represents a property of a location exposure. The file uses a delimiter character to organize text into discreet columns of structured data. The following text delimiters are supported: comma (,), semicolon (;), tab (^I), tilde (~).

The COUNTRYCODE and COUNTRYSCHEME properties are required. All other location properties are optional: ADMIN1NAME, CITYNAME, COUNTRYCODE, COUNTRYRMSCODE, COUNTRYSCHEME, ID, LATITUDE, LONGITUDE, NAME, POSTALCODE, and STREETADDRESS.

For example, the following snippet is an example of a flat file of exposure data that using the tilde character (~) as a text delimiter.

id~NAME~StreetAddress~PostalCode~CityName~Admin1Name~CountryCode~CountryRMSCode~CountryScheme~Latitude~Longitude
0~At Your Service Tax & Accounting~923 E KLOSTERMAN RD~~TARPON SPRINGS~FL~US~US~ISO2A~0.0~0.0
1~Gulf Coast Po Boys~312 W BAY DR~~LARGO~FL~US~US~ISO2A~0.0~0.0
2~Suncoast Baptist Association~6559 126TH AVE~~LARGO~FL~US~US~ISO2A~0.0~0.0
3~Rainbow Lanes~1225 S HIGHLAND AVE~~CLEARWATER~FL~US~US~ISO2A~0.0~0.0
4~Skinner & Associate Executive Search~220 TURTLE CREEK CIR~~OLDSMAR~FL~US~US~ISO2A~0.0~0.0
5~Superior Cleaning~1860 N FORT HARRISON AVE~~CLEARWATER~FL~US~US~ISO2A~0.0~0.0
6~Rachel's Color & Hairstyles~10871 ULMERTON RD~~LARGO~FL~US~US~ISO2A~0.0~0.0
7~Souhtside Church of Christ~1942 49TH ST S~~SAINT PETERSBURG~FL~US~US~ISO2A~0.0~0.0
8~Goodrich Lighting Services~129 FAIRFIELD ST~~OLDSMAR~FL~US~US~ISO2A~0.0~0.0
9~Marconi Search Consultants~2451 N MCMULLEN BOOTH RD~~CLEARWATER~FL~US~US~ISO2A~0.0~0.0
10~Ascend Engineering~8114 ULMERTON RD~~LARGO~FL~US~US~ISO2A~0.0~0.0
11~B D T Truck Bodies~4612 107TH CIR N~~CLEARWATER~FL~US~US~ISO2A~0.0~0.0
12~Off The Rack~7500 ULMERTON RD~~LARGO~FL~US~US~ISO2A~0.0~0.0
13~Lanier's Garage~6921 40TH ST N~~PINELLAS PARK~FL~US~US~ISO2A~0.0~0.0

Step 2: Create bulk geohaz folder

Use the Create Bulk Geohaz Folder operation to create a new BULK_GEOHAZ folder on AWS.

A BULK_GEOHAZ folder is a temporary storage location and a logical path on AWS S3. Once in place, we will upload the flat file of location exposure data to this folder.

The request body defines the folder.

{
  "properties": {
    "fileCompressionType": "GZIP",
    "fileExtension": "CSV"
  },
  "folderType": "BULK_GEOHAZ"
}

If successful, returns a 201 Created response that includes the unique folderId of the BULK_GEOHAZ folder and uploadUrls for that folder on AWS.

{
  "folderType": "BULK_GEOHAZ",
  "folderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "uploadDetails": {
    "uploadUrls": [
      "https://XXXXX.amazonaws.com/XXXXX/li-bulk/XXXXX/input/file?XXX"
    ]
  }
}

The uploadUrls array returns the URL of the BULK_GEOHAZ folder. This URL includes all of the security credentials needed to connect to the folder and upload the flat file.

Step 3: Upload flat file to geohaz folder

Use the Amazon AWS API to upload the flat file of location exposure data to the BULK_GEOHAZ folder.

If a fileCompressionType is specified in Step 2, the flat file uploaded must be compressed using the specified format prior to uploading.

The Bulk Geohaz API does not provide operations for uploading location exposure data to Amazon S3. For that, you can use Amazon AWS API. Amazon S3 APIs enable tenants to upload data to BULK_GEOHAZ folders on Amazon Simple Storage Service (Amazon S3).

https://XXXXXXXXXX.amazonaws.com/rms/li-bulk/XXXXX/input/file?
X-Amz-Security-Token=XXXXXXXXXX&
X-Amz-Algorithm=XXXXXXXXXX&
X-Amz-Date=XXXXXXXXXX&
X-Amz-SignedHeaders=XXXXXXXXXX&
X-Amz-Expires=XXXXXXXXXX&
X-Amz-Credential=XXXXXXXXXX&
X-Amz-Signature=XXXXXXXXXX

Step 4: Geohazard exposure data

Use the Create Bulk Geohaz Job operation to geocode the location exposures defined in the uploaded flat file.

The request body must specify the folderId of the BULK_GEOHAZ folder and the delimiter that identifies columns of data in the uploaded flat file.

{
  "settings": {
    "folderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "delimiter": "TILDE",
    "jobName": "geohaz new sites",
    "layers": [
      {
        "options": {
          "newKey": "New Value",
          "newKey-1": "New Value"
        }
      }
    ]
  }
}

The request body accepts name and version of the layer data product as well as a number of options:

If successful, this operation returns a 202 Accepted response in the Location header and a URI that includes the jobId of the BULK_GEOHAZ job. You can use this URI to poll the status of the job. See Get Bulk Geohaz Job for details.

Once the job is complete, returns a URI that enables you to download the geocoding results. Geocode results are compressed using the same format specified in Step 2.