Subscription Weather API (1.0.0)

Download OpenAPI specification:Download

The HailTrace App offers powerful lead-generation features. Our OpenAPI is designed to allow our customers to generate even more value from our application by giving them the tools to interact with their data. See our intro to get started.

The Subscription Weather API only grants an integrator access to the weather data that a specific user has access to based on his/her subscription. For instance, a user may have a subscription to Texas for Wind, Tornado, and Hail.

Use Case Warning

This endpoint is not meant for forensic or insurance use-cases. It is merely to be used for rendering the user's purchased maps in a UI. For instance, if you have a canvassing app and want to integrate HailTrace customers, you would use these endpoints to search for and display HailTrace App weather data.

Using these endpoints for anything other than visualizing and searching for HailTrace App weather data is a breach of our TOS.

What you can do:

Temporarily store catalog data (lists of available maps)
Visualize GeoJSON shape data in your UI as an overlay.

What you can not do:

Replicate other HailTrace App Features.
Store Shape Data in a Database.

If you're looking to create other more advanced use-cases, please reach out to our team.

Authentication

apiKey

The API key procured by the user in the HailTrace User Settings.

Security Scheme Type	API Key
Header parameter name:	X-API-Key

appId

The unique application secret aquired from the HailTrace Team.

Security Scheme Type	API Key
Header parameter name:	X-APP-ID

Weather Events (Maps)

Search Weather Events

Allows the client to search for existing weather events on a specific date.

Authorizations:

apiKey

appId

Request Body schema: application/json

latitude	number [ -90 .. 90 ] The latitude to search for weather events around.
longitude	number [ -180 .. 180 ] The longitude to search for weather events around.
search_radius_mi	string [ 3 .. 25 ] Default: 3 The radius to search for maps around a specific location. Cannot be less than 3 Mi or more than 80 Mi.
page_size	integer [ 100 .. 500 ] Default: 100 The number of events to return. Defaults to 100. <= 500; >=100
page	integer >= 1 Default: 1 The page number.
start_date required	string <date> The date to start the search on.
end_date required	string <date> The date to end the search on.
weather_types	Array of any[ items ] Items Enum: "ALGORITHM_HAIL_SIZE" "METEOROLOGIST_HAIL_SIZE" "METEOROLOGIST_WIND_SPEED" "METEOROLOGIST_TORNADO" Limits the results to the selected weather types, or if left empty returns all types.
min_hail_size	number >= 0.75 If set, filters out all weather events with a hail size lower than min_hail_size. Only applies to weather events with the type `METEOROLOGIST_HAIL_SIZE` or `ALGORITHM_HAIL_SIZE`.
max_hail_size	number >= 0.75 If set, filters out all weather events with a hail size greater than max_hail_size. Only applies to weather events with the type `METEOROLOGIST_HAIL_SIZE` or `ALGORITHM_HAIL_SIZE`.
min_wind_speed_mph	integer [ 0 .. 300 ] If set, filters out all weather events with a wind speed less than the one provided. Only applies to weather events with the type `METEOROLOGIST_WIND_SPEED`.
max_wind_speed_mph	integer [ 0 .. 300 ] If set, filters out all weather events with a wind speed greater than the one provided. Only applies to weather events with the type `METEOROLOGIST_WIND_SPEED`.
min_tornado_ef_rank	integer [ 0 .. 5 ] If set, filters out all weather events with a tornado EF Rank less than the value provided. Only applies to weather events with the type `METEOROLOGIST_TORNADO`.
max_tornado_ef_rank	integer [ 0 .. 5 ] If set, filters out all weather events with a tornado EF Rank less than the value provided. Only applies to weather events with the type `METEOROLOGIST_TORNADO`.
include_shapes	boolean Default: false If set to true, the payload will return the shapes within the location and radius selected (up to 30 miles) based on the user's subscription. The date-range must be 30 days or lower to use this property.

Responses

Request samples

Payload

Content type

application/json

{"latitude": -90,
"longitude": -180,
"search_radius_mi": 3,
"page_size": 100,
"page": 1,
"start_date": "2018-04-19",
"end_date": "2019-12-25",
"weather_types": ["ALGORITHM_HAIL_SIZE"
],
"min_hail_size": 0.75,
"max_hail_size": 0.75,
"min_wind_speed_mph": 300,
"max_wind_speed_mph": 300,
"min_tornado_ef_rank": 5,
"max_tornado_ef_rank": 5,
"include_shapes": false
}

Response samples

Content type

application/json

{"page": 1,
"page_size": 10,
"results": [{"date": "2019-08-24",
"max_algorithm_hail_size": 1,
"max_meteorologist_hail_size": 1.75,
"max_meteorologist_wind_speed_mph": 30,
"shapes": [{"weather_type": "ALGORITHM_HAIL_SIZE",
"meta": {"date": "2019-08-24",
"hail_size_duration_minutes": 1,
"hail_size_inches": 1.25,
"wind_speed_mph": 30,
"tornado_ef_rank": 5,
"isolated": false,
"estimated_house_count": 13000
},
"geometry": {"type": "Point",
"coordinates": [[[0,
0
]
]
]
}
}
]
}
]
}

Get Weather Event By Date

Returns a complete weather event for the date provided. Includes the weather-event shape geometries.

Authorizations:

apiKey

appId

path Parameters

date

required

string

Example: 2020-01-01

The date of the weather event to pull data for in the format YYYY-MM-DD.

Responses

Response samples

Content type

application/json

{"date": "2019-08-24",
"max_algorithm_hail_size": 1,
"max_meteorologist_hail_size": 1.75,
"max_meteorologist_wind_speed_mph": 30,
"shapes": [{"weather_type": "ALGORITHM_HAIL_SIZE",
"meta": {"date": "2019-08-24",
"hail_size_duration_minutes": 1,
"hail_size_inches": 1.25,
"wind_speed_mph": 30,
"tornado_ef_rank": 5,
"isolated": false,
"estimated_house_count": 13000
},
"geometry": {"type": "Point",
"coordinates": [[[0,
0
]
]
]
}
}
]
}

Location

Impact History at Location

This endpoint returns the history of weather impacts at the given latitude and longitude.

Authorizations:

apiKey

appId

query Parameters

latitude required	number
longitude required	number

Responses

Response samples

Content type

application/json

[{"date": "2021-12-21",
"weather_type": "ALGORITHM_HAIL_SIZE",
"hail_size_inches": 1.75,
"wind_speed_mph": 30
}
]

Order Impact History PDF Report

Authorizations:

apiKey

appId

Request Body schema: application/json

name required	string The name of the owner contact.
phone_number	string <phone> The phone number of the owner contact.
insurance_carrier	string The insurance carrier of the owner contact.
insurance_claim_number	string The insurance claim number of the owner contact.
roof_replacement_date	string <date> The date the roof was last replaced.
roof_type	any (RoofType) Enum: "T_LOCK_SHINGLE" "ASPHALT_SHINGLE_25YR" "ASPHALT_SHINGLE_30YR" "ASPHALT_SHINGLE_40YR" "ASPHALT_DESIGNER_SHINGLE_30YR" "ASPHALT_SHINGLE_CLASS4" "ASPHALT_DESIGNER_SHINGLE_CLASS4" "ASBESTOS_SHINGLE" "CONCRETE_TILE" "CLAY_TILE" "SLATE_TILE" "METAL_TILE" "PLASTIC_TILE" "METAL_24GA" "METAL_26GA" "METAL_29GA" "ALUMINUM_METAL_26GA" "ALUMINUM_METAL_29GA" "COPPER_METAL_24GA" "COPPER_METAL_26GA" "TPO_MEMBRANE" "PVC_MEMBRANE" "EPDM_MEMBRANE" "MODIFIED_BITIUM_MEMBRANE" "ROCK_BALLASTED" "WOOD_SHAKE" An enum describing the types of roofs.
required	object (Location) A specific location with it's address and coordinates.

Responses

Request samples

Payload

Content type

application/json

{"name": "Jeff Bezos",
"phone_number": "13134828760",
"insurance_carrier": "Ameca Insurance",
"insurance_claim_number": "INS-1023",
"roof_replacement_date": "2022-01-22",
"roof_type": "T_LOCK_SHINGLE",
"location": {"house_number": "string",
"street_name": "string",
"state": "string",
"country": "string",
"zipcode": "string",
"city": "string",
"address": "string",
"address2": "string",
"full_address": "string",
"geometry": {"type": "Point",
"coordinates": [0,
0
]
}
}
}

Response samples

Content type

application/json

{"url": "string"
}

System

Server heartbeat operation

This operation shows how to override the global security defined above, as we want to open it up for all users.