Overview

Geocoding is the "gateway" to all Moody's RMS risk analysis processes. Geocoding identifies the global coordinates of a physical address so that it may be analyzed using a model.

In Climate On Demand, the physical address of a facility can be explicitly specified in the body of the request using the latitude and longitude parameters or generated automatically using the Moody's RMS geocoding service. If the later option is chosen, special care must be taken to ensure that the resulting coordinates are accurate and consistent with the coordinates used in previous analyses.

Specifying global coordinates

Moody's RMS recommends that that you specify the latitude and longitude coordinates of a physical address whenever you hazard score or impact score a facility.

In the following risk category scoring example, the latitude and longitude of the facility is explicitly specified.

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

When these coordinates are specified in the request, the response indicates that this is the case.

Status	Description
`user`	The client specified the latitude and longitude in the request.

Using the geocoding service

Moody's RMS recommends that you specify the latitude and longitude of a facility whenever possible.

If a request does not explicitly specify the latitude and longitude parameters, the API automatically calls the Moody's RMS geocoding service and uses the returned coordinates to complete scoring.

In the following risk category scoring example, the latitude and longitude of the facility are not specified. The latitude and longitude attributes are option.

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

Moody's RMS recommends that you carefully review the coordinates returned by the geocoding service for accuracy and to ensure that the coordinates are consistent with your expectations and knowledge about the facility, i.e. that the coordinates match prior geocoding requests for the same address.

Response codes

Climate on Demand API responses return status codes that enable you to interpret and validate the results returned by the geocoding service.

The geo_status attribute may indicate the accuracy of the results by identifying the level of certainty of the geocoded results:

{
    "job_id": 1676,
    "user_id": 639,
    "status": "FINISHED",
    "percent_complete": 100,
    "output": [
        {
            "id": "1",
            "geo_status": "User",
            "risk_categories": {...},
            ...
        }
    }],
    "start_date": "Sept 27, 2023, 5:46:59 PM",
    "end_date": "Sept 27, 2023, 5:47:04 PM"
}

In this example, the response indicates that the analysis is based upon the latitude and longitude coordinates specified by the User in the request. If you specify the coordinates yourself, you can be certain that the analysis is based on the correct location of the facility.

If the value of the geo_status attribute is anything other than User, that indicates the Moody's geocoding service was used to identify the geospatial coordinates of facility's location.

Depending on the information provided in the request, the geocoding service may provide varying levels of certitude. The table lists geolocation statuses by level of certitude:

Status	Description
User	Analysis is based on the latitude and longitude specified in the request. You can be certain that the location is accurate.
Building	Analysis is based on a lookup the latitude and longitude coordinates by the geocoding service. The coordinates were found with a high degree of precision.
Block Segment	The geocoding service accepts a highly detailed postal code such as UK postcode unit or Canadian 6-digit Local Delivery Unit (LDU) point that usually matches to within a block or better to the true location.
Street Name	For selected countries, the geocoding service achieves a level of positional accuracy based upon the centroid along a set of street segments representing the street and an enclosing geography such as the post code.
Medium Resolution PostalCode	The geocoding service places the location on the centroid of the postal code (e.g. US ZIP Code) in which it falls. In the US postal code centroids are exposure and population weighted to provide a better representation of exposure. Population-weighted centroids and geographic centroids are not usually the same place.
Admin4	In some countries, a district level is used that generally provides geocoding at a resolution between city and postal code.
City	The geocoding service searches using city name and the corresponding county or state. In cases where postal information is scarce, the geocoding service may return a centroid for the city.
Admin3	The geocoding service searches using the Admin3 name and the corresponding Admin2 and Admin1. In cases where postal information is scarce, the geocoding service may return a centroid for the district or similar resolution information. In some counries, an Admin3 level is considered higher resolution than a city (e.g. an Israeli Yishuv or Mexican Colonia), or lower than a city (e.g. a German Gemeinde).
Admin2	The geocoding service has validated the names of the country/state or similar resolution data and set the value of both the latitude and longitude to zero.
Admin1	The geocoding service has validated the names of the country/state or similar resolution data and set the value of both the latitude and longitude to zero.
CRESTA (Zone1)	Defined by CRESTA.org, and used by insurers and reinsurers around the world to manage and report accumulated catastrophe loss exposure and set rets. If the CRESTA zone is the only data element available, the geocoding service validates the CRESTA zone ID and sets the latitude and longitude to zero.
Country	The specified address is not available to you under the terms of your license agreement with Moody’s RMS. If this status is returned and you think it may be an error, contact `[email protected]`.
Multiple Match	Within a country, not all address information is unique. Street names and city names are the most common elements of address information that might have multiple matches – that is, multiple instances of the same spelling in the Moody’s RMS databases for a given country. The geocoding engines will determine the best rank order of multiple matches based on a series of factors, and will automatically choose the first match in the list. This may not be the right match and so users are encouraged to investigate further the proper coordinates for assets returned with this code.Not Found – the geocoding service could not find the address. In this case, “null” is returned for latitude, longitude and elevation