Catastrophe zones

A catastrophe zone refers to the geographical region the catastrophe occurred in. For example, if a hurricane hit the state of Florida, Florida would be the catastrophe zone.

This topic provides a high-level overview of catastrophe zones, discussing both what they are and how to work with them through the system APIs.

For a more detailed discussion of the business functionality of catastrophe zones, refer to Application Guide.

Querying for catastrophe zones

Use the following endpoints to query for catastrophe zones:

  • GET /admin/v1/catastrophes/{catastropheId}/catastrophe-zones
  • GET /admin/v1/catastrophes/{catastropheId}/catastrophe-zones/{catastropheZoneId}

For example, the following request retrieves all the catastrophe zones associated with the catastrophe xc:SAw_jS2RygUX4uS9idwqV.

Command

GET /admin/v1/catastrophes/xc:SAw_jS2RygUX4uS9idwqV/catastrophe-zones
Response
{
    "count": 2,
    "data": [
        {
            "attributes": {
                "code": "TN",
                "country": {
                    "code": "US",
                    "name": "United States"
                },
                "id": "xc:SB7iLGBxlHbxNnv298n3E",
                "zoneType": {
                    "code": "state",
                    "name": "State"
                }
            }
        },
        {
            "attributes": {
                "code": "FL",
                "country": {
                    "code": "US",
                    "name": "United States"
                },
                "id": "xc:SUHNlpXQePg82I-hWKa3v",
                "zoneType": {
                    "code": "state",
                    "name": "State"
                }
            }
        }
    ]
}

The API responds with all the catastrophe zones associated with the hurricane. You can also retrieve details for a specific catastrophe zone by its ID. For example, the following request retrieves information about only Florida, xc:SUHNlpXQePg82I-hWKa3v.

Command
GET /admin/v1/catastrophes/xc:SAw_jS2RygUX4uS9idwqV/catastrophe-zones/xc:SUHNlpXQePg82I-hWKa3v
Response
{
    "data": {
        "attributes": {
            "code": "FL",
            "country": {
                "code": "US",
                "name": "United States"
            },
            "id": "xc:SUHNlpXQePg82I-hWKa3v",
            "zoneType": {
                "code": "state",
                "name": "State"
            }
        }
    }
}

Creating catastrophe zones

Use the following endpoint to create a catastrophe zone:

  • POST /admin/v1/catastrophes/{catastropheId}/catastrophe-zones

To create a catastrophe zone, you must specify the id of its associated geographic zone. To learn how to find a geographic zone, refer to Geographic zones.

Once you have found the geographic zone's id, you can create the catastrophe zone. For example, the following request creates a catastrophe zone associated with the geographic zone of Florida.

Note: There is no PATCH for catastrophe zones, so when you want to make changes to a catastrophe zone, you should use a DELETE to delete the existing zone and a POST to replace it with an updated zone.

Command

POST /admin/v1/catastrophes/xc:SAw_jS2RygUX4uS9idwqV/catastrophe-zones

Request


{
    "data": {
        "attributes": {
            "geographicZone": {
                "id": "US:SWt2SjaMi5c6JRuVoE5HA"
            }
        }
    }
}

Response


{
    "data": {
        "attributes": {
            "code": "FL",
            "country": {
                "code": "US",
                "name": "United States"
            },
            "id": "xc:SDI3Txt4aLtYGqyDeCI1e",
            "zoneType": {
                "code": "state",
                "name": "State"
            }
        }
    }
}

The API returns additional information about the created catastrophe zone, such as its country and state. It's important to note that the id the API returns is the new catastrophe zone id, xc:SDI3Txt4aLtYGqyDeCI1e.

Deleting catastrophe zones

Use the following endpoint to delete a catastrophe zone from its associated catastrophe:

  • DELETE /admin/v1/catastrophes/{catastropheId}/catastrophe-zones/{catastropheZoneId}

For example, the following request deletes the catastrophe zone, xc:SUHNlpXQePg82I-hWKa3v.

Command

DELETE /admin/v1/catastrophes/xc:SAw_jS2RygUX4uS9idwqV/catastrophe-zones/xc:SUHNlpXQePg82I-hWKa3v

When the API has successfully deleted the catastrophe zone from its associated catastrophe, it will return an empty body in response.