Overview

The Climate On Demand API supports the calculation of both hazard scores and financial impact scores by leveraging Intelligent Risk Platform.

Step 1: Obtain host name and API key

The Climate On Demand API restricts access to protected API resources by means of security credentials. A client application must pass valid security credentials in every request it makes to the API. These credentials enable the platform to authenticate the identity of the client and confirm that the client is authorized to access and leverage the requested resources.

Climate On Demand supports two authentication methods:

• The API key identifies a client application that is entitled to call the API. The API key provides the client with long-term access to API operations and resources.
• The access token identifies a user account that is entitled to call the API. The access token provides the client with temporary access to API operations and resources. OAuth access tokens are generated "on a per-session basis."

To learn more about these authentication methods and for step-by-step instructions on acquiring an API key or temporary access token, see Authentication and Authorization.

Step 2: Understand Climate On Demand API operation endpoints

An operation is a callable unit of a RESTful API that consists of an HTTP method (e.g. GET, POST, DELETE) and a URL that consists of a scheme, host, and a path that identifies the resource.

The host identifies the data center that hosts your company's tenant instance: api-euw1.rms.com or api-use1.rms.com. Whenever you see the {host} variable in an example, you must substitute the correct host name.

The path consists of an version path, operation path, and resource path.

• The app path identifies the application. For example, cod.
• The version path identifies the version of the data product. For example, v1.
• The operation path identifies the operation. For example, score-facilities-details.
• The resource path identifies the resource. For example, job. This operation and other operations like it create a job for calculating the requested scores.

The calculation of hazard scores and financial impact scores can take considerable time depending on the number of facilities analyzed and the details provided. Consequently, the Climate On Demand API manages these long-running processes means of workflow jobs which are processed by the Intelligent Risk Platform workflow engine.

All parameters for these operations are specified in the request body. The request body typically defines an object that defines two or more resource parameters. For example, the methodology parameter (m) and an array of facilities objects.

The next two steps in this procedure demonstrate this process. First, you will create a job that will calculate hazard scores for a specified facility. Then you will use the ID number of this job to retrieved the calculated results when the job is complete.

Step 3: Make a test API request

You can now confirm that the API key is working by making a request using the Climate On Demand API.

The following example walks through the JSON workflow. The Calculate Risk Category Scores resource calculates the financial impact of climate change for one or more facilities.

curl --request POST \
     --url https://{host}/AppsServices/api/v1/score-facilities-impact/jobs \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

The client passes its API key in the header.

All parameters are specified in the request body. The request body consists of an object that is defined by two attributes: the m (methodology) parameter and a facilities array that defines one or more facilities, which identify the assets to be scored.

If a value of 2023.1 is specified for the m (methodology) parameter in a request, the th (time horizon) parameter and s (scenario) parameter are also required.

{
    "m": "2022.1",
    "facilities": [{
        "id": "1",
        "name": "berkeley office",
        "activity": "office",
        "street1": "2000 hearst avenue",
        "city": "berkeley",
        "state": "ca",
        "postal_code": "94709",
        "country": "united states",
        "latitude": 37.8734494,
        "longitude": -122.2706614
    }] 
}

If successful, initiates a workflow job and returns a 200 response includes the job ID and job status (IN PROGRESS, FINISHED, FAILED):

{ 
    "job_id": 1676
}

Once the job is FINISHED, you can retrieve category scores for the specified facilities.

Step 4: Retrieve results

The Get Results by Job operation enables you to retrieve the results generated by a job by specifying the job ID as a path parameter. In this example, we'll use the job_id returned by the previous request in Step 3:

curl --request GET \
     --url https://{host}/AppsServices/api/jobs/1676 \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

If successful, the request returns a 200 http status code and the hazard scores calculated by the job.

{
    "job_id": 1676,
    "user_id": 639,
    "status": "FINISHED",
    "percent_complete": 100,
    "output": [
        {
            "id": "1",
            "name": "Berkeley Office",
            "m": "2023.3",
            "latitude": 37.8734494,
            "longitude": -122.2706614,
            "geo_status": "User",
            "elevation": 62.0,
            "th":"2050",
            "rcp": "RCP8.5",
            "score": 35.0,
            "risk_categories": {
                "Floods": {
                "score": 3.0,
                "risk level": "Low"
            },
            "Heat Stress": {
                "score": 33.0,
                "risk level": "Medium"
            },
            "Hurricanes & Typhoons": {
                "score": 0.0,
                "risk level": "None"
            },
            "Sea Level Rise": {
                "score": 25.0,
                "risk level": "Low"
            },
            "Water Stress": {
                "score": 72.0,
                "risk level": "High"
            },
            "Wildfire": {
                "score": 74.0,
                "risk level": "High"
            },
            "Earthquakes": {
                "score": 95.0,
                "risk level": "High"
            }
        }
    }],
    "start_date": "Sept 27, 2023, 5:46:59 PM",
    "end_date": "Sept 27, 2023, 5:47:04 PM"
}