Overview

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

In a future release, this operation will support hazarding of exposures in bulk.

Entitlements

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

• RI-RISKMODELER
• RI-UNDERWRITEIQ

Operations

The Bulk Geohaz API exposes the following operations:

Workflow

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"
        }
      }
    ]
  }
}

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.