Domino AI API
The OneConcern Domino AI APIs provide a mechanism to quantify physical risks to specific locations from catastrophes damaging individual properties and/or disrupting the networks upon which a property’s normal operations depend.
The OneConcern Domino AI APIs are organized around REST. The APIs have predictable resource-oriented URLs, accept JSON-encoded request bodies, return JSON-encoded responses, and use standard HTTP response codes and API tokens to authenticate requests.
Getting Started
This page describes the API functionality at a high level. Developers should consult the OpenAPI spec, which provides an authoritative programmatic description of the API implementation, including default request body entries, acceptable request body ranges, as well as return payload and header details.
Calculation Options
The Domino AI API structure is designed to support calculation option to better target the use case and reduce the payload size of data across the network. The details of this are described in the schema sections of the API Spec.
In addition to specifying the endpoint and latitude and longitude, API calls should also specify calculation options as described in the API Spec.
Responses
Our Domino AI API endpoints return a json-formatted response as described in the API Spec.
Authentication
API tokens can be obtained by contacting the One Concern customer success team cs@oneconcern.com. Note that your specific API token may provide authentication for only a subset of the endpoints described in the API Spec. The API spec serves to inform the full capability of our Domino AI API.
Your API tokens carry many privileges, so be sure to keep them secure! Do not share your secret API tokens in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the APIs is performed via key based authentication. Provide your API token as a key titled ‘x-1c-api-token’ in the request header.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Headers
Client ID
In addition to the x-1c-api-token header mentioned in the previous section, there is another required header that must be passed, called client-id.
This value can be anything meaningful to each customer. It is typically used when a single customer shares an API key across multiple groups, and the customer wishes to distinguish the calls made by each group.
One Concern will provide a breakdown of API calls by client-id as part of billing upon request.
Transaction ID
Another header may be optionally provided by each customer in order to uniquely track each call to the API. This header is called transaction-id, and it will also be provided with billing reports upon request.
Errors
One Concern uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was misspelled or missing, a parameter was outside the supported range, etc.). Codes in the 5xx range indicate an error with One Concerns’ servers (these are rare).
When there is no data for the given latitude and longitude and the request if property formatted, the API will issue “204 No Content”.
Some 4xx errors that could be handled programmatically (e.g., 401, 422) include an error message that briefly explains the error reported.
If the issued API token is not authorized, it will issue “401 Unauthorized”. In this case, please check with our customer success team cs@oneconcern.com to make sure you have a valid API token for the endpoint you are attempting to use.
When your API request contains the content that can not be handled by the API, it will issue “422 Unprocessable Content”. In the response body, there will be a detailed error message. For example:
"msg": "value is not a valid enumeration member; permitted: 'flood', 'wind', 'seismic'",In such a case, cross-reference with the schema detailed in the API Spec will likel resolve the error.
Versioning
The APIs return version information in the response header as 2 fields, so as to allow end-users to fully identify the version of metrics that have been provided by the API call, per the below description:
| Key Name | Meaning | Format |
|---|---|---|
| x-1c-api-version | Reflects the released version of API code returning the metrics | vX.Y.Z |
| x-1c-data-version | Reflects the data version that the API is consuming and creating metrics from | vUS.X.Y.Z |
Developers should expect that most backwards compatible changes to the API contract or metrics will result in no change to the API endpoints, instead simply resulting in a change to the x-1c-api-version returned in the header. Similarly, most data updates will not result in changes to the endpoints, just a change to the x-1c-data-version returned in the header.
Generally, when significant improvements are made from a modeling point of view, customers will be notified of this through the customer success team. Note that this may not result in a new endpoint being created, but simply a new respective version update, communicated via the header.
One Concern recommends that customers track the version information returned by individual API calls for use cases that require an audit trail of data used in their applications.