Overview

Climate on Demand hazard modeling enables organizations to evaluate the potential risk to their facilities posed by multiple risk categories. Facilities may be modeled at either that category-level (high-level) or at the subcategory-level, which evaluates and scores risk indicators within each risk category. This endpoint returns data at the risk sub-category level. It provides risk category scores as well as the sub-category measures and normalized scores.

Risk categories include Floods, Heat Stress, Hurricanes & Typhoons, Sea Level Rise, Water Stress, Wildfires, Earthquakes.

Risk Subcategory hazard modeling returns both hazard category-level hazard scores (risk score and risk level) and subcategory-level hazard scores. For each subcategory, subcategory-level hazard scoring calculates two hazard scores: measure and normalized_score.

The measure returns a calculated raw score for an indicator based on the location of the facility, the methodology specified, the time horizon, etc.
The normalized_score represents the relative exposure of the facility to the risk subcategory. This value is expressed as a percentage (0-100) that enables you to compare the exposure of different facilities. A low number represents relatively low risk and a high number relatively high risk.

In this tutorial, we will review the process for hazard modeling a facility at the subcategory-level. We will review key request parameters to understand how these parameters determine the results calculated. Finally, we will review the hazard scores returned. This process is described using sample code in cURL and Python.

Step 1: Calculate subcategory scores

The Calculate subcategory scores calculates the risk subcategory scores for the specified facilities.

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

All parameters are specified in the request body. The request body consists of an object with two fields – the methodology parameter and an array of facilities. For methodologies that support scenario analysis, two additional parameters are required.

{
    "m": "2022.1",
    "facilities": [{
        "id": "1",
        "name": "newark office",
        "activity": "office",
        "street1": "7575 gateway blvd., suite 300",
        "city": "newark",
        "state": "ca",
        "postal_code": "94560",
        "country": "united states",
        "latitude": 37.5412000000,
        "longitude": -122.060610000
    }] 
}

If the latitude and longitude are not provided, Climate on Demand Pro attempts to geocode the address. In this case, the API returns the geocoded latitude/longitude and a geocoding status code, which may include error messages. See Appendix 1 for information about geocoding status. We recommend that you carefully review geocoding results before running additional requests for the same facilities.

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 subcategory scores for the specified facilities.

Step 2: Get results

The Get results by job returns the risk data calculated by a specific job.

curl --request GET \
     --url https://[host]/AppsServices/api/jobs/jobId \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

If the specified job is finished, the response returns an output that includes the risk data. Depending on the resource used to initiate the job, the output attribute may include an array of risk category scores, risk subcategory scores, or financial impact scores:

{
    "job_id": 1678,
    "user_id": 639,
    "status": "FINISHED",
    "percent_complete": 100,
    "output": [
        {
            "id": "1",
            "name": "Newark Office",
            "m": "2023.3",
            "latitude": 37.5412000000,
            "longitude": -122.060610000,
            "geo_status": "User",
            "elevation": 62.0,
            "th": "2050",
            "rcp": "RCP8.5",
            "score": 35.0,
            "risk_categories": {
                "Floods": {
                "score": 3.0,
                "risk level": "Medium",
                "indicators": {
                    "Rainfall intensity": {
                        "measure": 0.0908,
                        "normalized_score": 54.0
                        },
                        "Very wet days": {
                            "measure": 0.7406,
                            "normalized_score": 24.0
                        },
                        "Absolute wet days": {
                            "measure": 0.5333
                            "normalized_score": 14.0
                        },
                        "Historical flood frequency": {
                            "measure": "Never Floods",
                            "normalized_score": 0.0
                        },
                        "Historical flood severity": {
                            "measure": 0.0,
                            "normalized_score": 0.0
                        }
                    }
                },
                "Heat Stress": {
                    "score": 33.0,
                    "risk level": "Medium",
                    "indicators": {
                        "Energy demand": {
                            "measure": 302.2827,
                            "normalized_score": 31.0
                        },
                        "Extreme temperature": {
                        "measure": 0.0714,
                        "normalized_score": 46.0
                        },
                        "Extreme heat days": {
                        "measure": 53.9058,
                        "normalized_score": 58.0
                        }
                    }
                },
            ....
    ],
    "start_date": "Sept 27, 2023, 6:05:14 PM",
    "end_date": "Sept 27, 2023, 6:05:17 PM"
}

Python example

def scoreFacilitiesImpact(token, request_json, host):
    endpoint = host + "/cod/AppsServices/api/v1/score-facilities-details/jobs"
    r = requests.post(url=endpoint, json=request_json, headers={'Authorization':'Bearer ' + token})
    print(f'response code: {r.status_code}') if r.status_code == requests.codes.ok:
        result = r.json()
        return result
else:        
    return None
def getJobResult(token, host, job_id):
    endpoint = host + "/cod/AppsServices/api/jobs/" + job_id
    r = requests.get(url=endpoint, headers={'Authorization': 'Bearer ' + token})
    print(f'response code: {r.status_code}')
    if r.status_code == requests.codes.ok:
        result = r.json()
        return result
else:
    return None
data = {
    "m": "P.2023.1",
    "th": "2050",
    "rcp": "RCP8.5",
    "facilities": [{
        "id": "1",
        "name": "newark office",
        "activity": "office",
        "street1": "7575 gateway blvd., suite 300",
        "city": "newark",
        "state": "ca",
        "postal_code": "94560",
        "country": "united states",
        "latitude": 37.5412000000,
        "longitude": -122.060610000
    }]
}
response_job = scoreFacilitiesDetails(access_token, data, my_host)
my_job = response_job.get('job_id')
time.sleep(30)
result = getJobResult(access_token, my_host, str(my_job))