API Reference

DOCUMENTATION

Everything you need to integrate StormPull into your application. All endpoints return JSON and require an API key via the Authorization header.

Authentication

All API requests require your API key in the X-API-Key header. Get your API key from the Dashboard.

curl https://stormpull.com/api/v1/hail/address?address=... \
  -H "X-API-Key: ht_live_your_key_here"

Base URL

https://stormpull.com/api

Endpoints

GET/v1/hail/address

Look up hail history for a US street address. The address is geocoded automatically and matched against NOAA radar and storm event data.

Parameters

Name	Type	Required	Default	Description
`address`	string	yes	—	Full US street address (e.g. "1234 Main St, Dallas, TX 75201")
`radius_miles`	number	no	`5`	Search radius in miles (max 25)
`years_back`	number	no	`5`	How many years of history to return (max 10)
`min_hail_size`	number	no	`0.75`	Minimum hail size in inches to include

Example Request

curl "https://stormpull.com/api/v1/hail/address?address=1234+Main+St,+Dallas,+TX+75201&radius_miles=5&years_back=5" \
  -H "X-API-Key: ht_live_your_key_here"

Example Response

{
  "address": {
    "input": "1234 Main St, Dallas, TX 75201",
    "formatted": "1234 Main St, Dallas, TX 75201, USA",
    "lat": 32.7876,
    "lon": -96.7985,
    "confidence": "ROOFTOP"
  },
  "search": {
    "radius_miles": 5,
    "years_back": 5,
    "min_hail_size": 0.75
  },
  "results": {
    "events_found": 12,
    "events": [
      {
        "date": "2024-06-12",
        "hail_size_inches": 1.75,
        "source": "MESH",
        "distance_miles": 0.8,
        "lat": 32.789,
        "lon": -96.801
      }
    ]
  },
  "usage": {
    "lookups_used": 47,
    "lookups_included": 2500,
    "is_overage": false
  }
}

GET/v1/hail/coordinate

Look up hail history for a specific latitude/longitude within CONUS (continental US). Use this when you already have geocoded coordinates.

Parameters

Name	Type	Required	Default	Description
`lat`	number	yes	—	Latitude (24 to 50)
`lon`	number	yes	—	Longitude (-125 to -66)
`radius_miles`	number	no	`5`	Search radius in miles (max 25)
`years_back`	number	no	`5`	How many years of history to return (max 10)
`min_hail_size`	number	no	`0.75`	Minimum hail size in inches to include

Example Request

curl "https://stormpull.com/api/v1/hail/coordinate?lat=32.7876&lon=-96.7985&radius_miles=3" \
  -H "X-API-Key: ht_live_your_key_here"

Example Response

{
  "coordinates": {
    "lat": 32.7876,
    "lon": -96.7985
  },
  "search": {
    "radius_miles": 3,
    "years_back": 5,
    "min_hail_size": 0.75
  },
  "results": {
    "events_found": 8,
    "events": [
      {
        "date": "2024-06-12",
        "hail_size_inches": 2.0,
        "source": "MESH",
        "distance_miles": 1.2,
        "lat": 32.791,
        "lon": -96.802
      }
    ]
  },
  "usage": {
    "lookups_used": 48,
    "lookups_included": 2500,
    "is_overage": false
  }
}

GET/v1/account/usage

Check your current usage and plan limits. This endpoint does not count as a lookup.

Parameters

Name	Type	Required	Default	Description

Example Request

curl "https://stormpull.com/api/v1/account/usage" \
  -H "X-API-Key: ht_live_your_key_here"

Example Response

{
  "plan": "starter",
  "lookups_used": 47,
  "lookups_included": 2500,
  "overage": false,
  "total_api_calls": 156,
  "calls_last_24h": 12
}

Rate Limits

Rate limits are enforced per API key based on your plan:

Plan	Requests/min	Lookups/mo
Sandbox	10	250 total
Starter	60	2,500
Growth	120	10,000
Scale	300	40,000

Errors

All errors return a JSON body with an error object containing code, message, and docs fields.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, revoked, or malformed.",
    "docs": "https://stormpull.com/docs/errors#INVALID_API_KEY"
  }
}

Status	Code	Description
`400`	`INVALID_ADDRESS`	Address could not be geocoded with sufficient confidence.
`400`	`INVALID_PARAMS`	A required parameter is missing or invalid.
`401`	`INVALID_API_KEY`	API key is missing, revoked, or malformed.
`402`	`PAYMENT_REQUIRED`	Account over limit with no valid payment method.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests per minute for your plan.
`500`	`INTERNAL_ERROR`	Internal server error. Retry with exponential backoff.

Data Sources

MESH (NEXRAD Radar)

Maximum Estimated Size of Hail from NOAA NEXRAD
~1km spatial resolution
Available from 2020 to present
Ingested nightly
Precise lat/lon coordinates

Storm Events (NOAA)

NOAA's curated severe weather database
County-level resolution
Available from 1950 to present
Updated monthly
Includes ground reports and damage data