Quick start BASE · api.hailsentinel.com/v1

Up and running in minutes.

Authenticate with your API key and start querying real-time hail data immediately.

Base URL

https://api.hailsentinel.com/v1

Authentication

All requests require a Bearer token in the Authorization header. Obtain your API key from the developer dashboard after signing up.

Rate limits

Every API key is capped at 60 requests/minute. Plans differ by monthly query allowance and webhook access, not request rate. Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Response format

All responses are JSON, returned as the resource directly (e.g. a cells array for detections, an hourly array for forecasts) — no envelope wrapper. Errors include a machine-readable error code and a human-readable message.

# Get current hail activity near Denver, CO
curl "https://api.hailsentinel.com/v1/hail/current\
?lat=39.7392&lon=-104.9903&radius_km=25" \
  -H "Authorization: Bearer hs_live_abc123..."

{
  "active": true,
  "detail": "standard",
  "summary": {
    "total_cells": 3,
    "max_size_mm": 32,
    "closest_cell_km": 4.2,
    "max_size_category": "quarter"
  },
  "cells": [
    {
      "geohash5": "9xj64",
      "lat": 39.7412,
      "lon": -104.9876,
      "distance_km": 4.2,
      "age_seconds": 95,
      "last_detected": "2026-02-28T18:42:00Z",
      "scan_count": 4,
      "hail": {
        "estimated_size_mm": 32,
        "ml_predicted_size_mm": 28,
        "size_category": "quarter",
        "confidence": 0.87
      }
    }
  ],
  "query": { "lat": 39.7392, "lon": -104.9903, "radius_km": 25, "lookback_minutes": 30 }
}

Authentication BEARER · HS_LIVE_* · HS_TEST_*

Secure API access.

Every request is authenticated with a Bearer token tied to your account. Separate keys for development and production.

Prefixed with hs_live_. Use in production environments. Requests count against your billing quota and return real data.

Prefixed with hs_test_. Use during development. Returns simulated data. Free of charge for development.

# Include your API key in the Authorization header
curl "https://api.hailsentinel.com/v1/hail/current?lat=39.7392&lon=-104.9903" \
  -H "Authorization: Bearer hs_live_a1b2c3d4e5f6..."

256-bit encryption

GCP secured infrastructure

99.5% uptime target

Core endpoints REFERENCE · 7 ENDPOINTS

API reference.

Seven endpoints covering real-time detection, alerting, historical data, and climatological risk.

Hail detection

GROUP · 3 ENDPOINTS

GET /v1/hail/current

Returns active hail cells within a given radius of a location (last 30 minutes). Data is sourced from multi-source radar composites processed through our detection pipeline.

Query parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)
`radius_km`	number	No	Search radius in kilometers. Default: `50`, max: `150`
`detail`	string	No	`standard` (default) or `advanced` for full radar, storm-structure, and impact fields

Response example

{
  "active": true,
  "detail": "standard",
  "summary": { "total_cells": 3, "max_size_mm": 32, "closest_cell_km": 4.2 },
  "cells": [
    {
      "geohash5": "9xj64",
      "lat": 39.7412,
      "lon": -104.9876,
      "distance_km": 4.2,
      "hail": { "estimated_size_mm": 32, "confidence": 0.87 }
    }
  ]
}

GET /v1/hail/forecast

Returns an hourly hail probability forecast for a location, up to 48 hours out. Combines HRRR model output with our ML post-processing layer.

Query parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)
`hours`	number	No	Forecast window in hours. Range: `1`–`48`, default: `24`

Response example

{
  "location": { "lat": 39.7392, "lon": -104.9903, "geohash4": "9xj6" },
  "model": { "name": "HRRR", "run_time": "2026-02-28T18:00:00Z", "source": "NOAA" },
  "peak": {
    "valid_time": "2026-02-28T20:00:00Z",
    "hail_probability": 0.72,
    "estimated_size_mm": 28,
    "risk_category": "elevated"
  },
  "hourly": [
    {
      "valid_time": "2026-02-28T19:00:00Z",
      "hail_probability": 0.45,
      "estimated_size_mm": 19,
      "risk_category": "moderate",
      "risk_score": 58
    }
  ],
  "count": 12
}

GET /v1/hail/history

Retrieves historical hail events near a location over a lookback window. Useful for insurance risk assessment, claims validation, and climatological analysis.

Query parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)
`radius_km`	number	No	Search radius in kilometers. Default: `25`, max: `100`
`days`	number	No	Lookback window in days. Default: `30`, max: `365`
`min_size_mm`	number	No	Minimum hail size to include, in mm
`limit`	number	No	Max events to return. Default: `50`, max: `200`

Response example

{
  "events": [
    {
      "storm_date": "2025-06-14",
      "location": { "lat": 39.74, "lon": -104.98, "geohash5": "9xj64" },
      "distance_km": 3.1,
      "duration_minutes": 18,
      "scan_count": 9,
      "hail": { "estimated_size_mm": 44, "size_category": "golf ball", "confidence": 0.91 }
    }
  ],
  "count": 1,
  "detail": "standard"
}

Alerts

GROUP · 3 ENDPOINTS

POST /v1/alerts/subscribe

Creates a new alert subscription for a location. When hail exceeding your threshold is detected, a webhook is dispatched to your specified URL. The response includes a one-time <code>webhook_secret</code> for HMAC verification — store it.

Request body

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)
`webhook_url`	string	Yes	HTTPS URL to receive webhook POST requests
`radius_km`	number	No	Alert radius in kilometers. Default: `25`, max: `100`
`min_mesh_mm`	number	No	Minimum hail size in mm to trigger the alert. Default: `25`
`name`	string	No	Human-readable label for the subscription

Response example

{
  "id": "sub_8f7e6d5c4b3a",
  "name": "Denver warehouse",
  "lat": 39.7392,
  "lon": -104.9903,
  "radius_km": 25,
  "min_size_mm": 25,
  "webhook_url": "https://example.com/webhooks/hail",
  "webhook_secret": "whsec_3a1f...(store this)",
  "status": "active"
}

GET /v1/alerts/{id}

Retrieves details of an alert subscription, including its configuration and a list of recently triggered alerts.

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Subscription ID (e.g., `sub_8f7e6d5c4b3a`)

Response example

{
  "id": "sub_8f7e6d5c4b3a",
  "name": "Denver warehouse",
  "lat": 39.7392,
  "lon": -104.9903,
  "radius_km": 25,
  "min_mesh_mm": 25,
  "webhook_url": "https://example.com/webhooks/hail",
  "status": "active",
  "trigger_count": 3,
  "created_at": "2026-02-28T14:30:00Z",
  "last_triggered_at": "2026-02-27T21:15:00Z"
}

DELETE /v1/alerts/{id}

Cancels an active alert subscription. Webhooks will no longer be dispatched for this subscription after cancellation.

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Subscription ID to cancel

Response example

{
  "success": true
}

Risk & climatology

GROUP · 1 ENDPOINT

GET /v1/hail/risk

Returns a climatological hail risk assessment for a location — annual and monthly probabilities (any / severe / significant / giant), a composite risk score, and a risk tier. Built from 5+ years of verified storm history.

Query parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)

Response example

{
  "location": {
    "lat": 39.7392,
    "lon": -104.9903,
    "geohash4": "9xj6"
  },
  "annual": {
    "any": 0.41,
    "severe": 0.12,
    "significant": 0.03,
    "score": 73,
    "risk_tier": "high",
    "peak_month": 6,
    "years_of_data": 5
  },
  "monthly": [
    { "month": 6, "probability": { "any": 0.18, "severe": 0.06 }, "score": 88 }
  ]
}

Webhooks & SDKs EVENTS · HMAC-SHA256 · SDKS

Event-driven integration.

Receive push notifications via webhooks and integrate faster with native SDKs for Python, JavaScript, and Java.

Subscribe to real-time events. Each webhook POST includes an X-Hailsentinel-Signature header for HMAC-SHA256 verification.

hail.detected Hail activity detected above your threshold at a monitored location.
hail.cleared Active hail event has ended and all-clear conditions are confirmed.
alert.created A new alert has been generated based on your subscription criteria.
alert.resolved A previously active alert has been resolved as conditions have changed.
risk.changed The risk score for a monitored location has changed by more than 10 points.

Retry policy

Failed deliveries are retried 3 times with exponential backoff: 1 second, 30 seconds, and 5 minutes. All payloads are signed with HMAC-SHA256 using your webhook secret.

{
  "event": "hail.detected",
  "timestamp": "2026-02-28T18:42:00Z",
  "data": {
    "subscription_id": "sub_8f7e6d5c4b3a",
    "estimated_size_mm": 32,
    "confidence": 0.87,
    "location": {
      "lat": 39.7412,
      "lon": -104.9876
    }
  }
}

SDK installation

Python

pip install hailsentinel

JavaScript

npm install @hailsentinel/sdk

Java (Maven)

<dependency>
  <groupId>com.hailsentinel</groupId>
  <artifactId>hailsentinel-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

Plan	Requests / min	Queries / month	Webhooks
Starter	60	100	—
Pro	60	2,000	✓
Business	60	10,000	✓

Ready to build?

Get started with our API today. Request an API key to access real-time hail detection, alerts, forecasts, and climatological risk.

Request API key Join early access

Get started FREE TIER · WAITLIST OPEN

Ready to protect what matters?

AI-powered hail intelligence to stay ahead of severe weather — for homeowners, businesses, and anyone who needs to know.

Get Early Access Book a demo

Free tier available · Join the early access waitlist