Developers

API Documentation

Integrate real-time hail detection, alerts, and radar data into your applications.

Quick Start

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

Rate limits vary by plan tier, from 10 requests/min on the Free plan to custom limits on Business. Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Response Format

All responses are JSON. Successful requests return a data wrapper. Errors include a machine-readable code and human-readable message.

Request
# Get current hail activity near Denver, CO
curl "https://api.hailsentinel.com/v1/hail/current\
?lat=39.7392&lng=-104.9903&radius_km=25" \
  -H "Authorization: Bearer hs_live_abc123..." \
  -H "Content-Type: application/json"
Response 200 OK
{
  "data": [
    {
      "storm_id": "ST-20260228-CO-0042",
      "coordinates": { "lat": 39.7412, "lng": -104.9876 },
      "mesh_size_mm": 32,
      "probability": 0.87,
      "detected_at": "2026-02-28T18:42:00Z",
      "direction_deg": 225,
      "speed_kph": 48
    }
  ],
  "meta": { "request_id": "req_9f8e7d6c", "timestamp": "2026-02-28T18:42:05Z" }
}

Authentication

Secure API Access

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

Live Keys

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

Test Keys

Prefixed with test_. Use during development. Returns simulated data. Free of charge, with relaxed rate limits for faster iteration.

Bearer Token Authentication
# Include your API key in the Authorization header
curl "https://api.hailsentinel.com/v1/hail/current?lat=39.7392&lng=-104.9903" \
  -H "Authorization: Bearer hs_live_sk_a1b2c3d4e5f6..."
256-bit Encryption
GCP Secured Infrastructure
99.9% Uptime Target

Core Endpoints

API Reference

Eight endpoints covering real-time detection, alerting, historical data, location risk, and radar imagery.

Hail Detection

GET /v1/hail/current

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

Query Parameters

ParameterTypeRequiredDescription
latnumberYesLatitude (-90 to 90)
lngnumberYesLongitude (-180 to 180)
radius_kmnumberNoSearch radius in kilometers. Default: 25, max: 150

Response Example

{
  "data": [
    {
      "storm_id": "ST-20260228-CO-0042",
      "coordinates": { "lat": 39.7412, "lng": -104.9876 },
      "mesh_size_mm": 32,
      "probability": 0.87,
      "direction_deg": 225,
      "speed_kph": 48
    }
  ]
}
GET /v1/hail/forecast

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

Query Parameters

ParameterTypeRequiredDescription
latnumberYesLatitude (-90 to 90)
lngnumberYesLongitude (-180 to 180)
hoursnumberNoForecast window in hours. Range: 1-48, default: 12

Response Example

{
  "data": [
    {
      "time": "2026-02-28T19:00:00Z",
      "probability": 0.45,
      "max_size_mm": 19,
      "confidence": 0.82
    },
    {
      "time": "2026-02-28T20:00:00Z",
      "probability": 0.72,
      "max_size_mm": 28,
      "confidence": 0.76
    }
  ]
}
GET /v1/hail/history

Retrieves historical hail events for a location within a date range. Useful for insurance risk assessment, claims validation, and climatological analysis.

Query Parameters

ParameterTypeRequiredDescription
latnumberYesLatitude (-90 to 90)
lngnumberYesLongitude (-180 to 180)
start_datestringYesStart date in ISO 8601 format (YYYY-MM-DD)
end_datestringYesEnd date in ISO 8601 format (YYYY-MM-DD)

Response Example

{
  "data": [
    {
      "date": "2025-06-14",
      "max_size_mm": 44,
      "duration_minutes": 18,
      "damage_estimate": "moderate",
      "storm_id": "ST-20250614-CO-0117"
    }
  ]
}

Alerts

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.

Request Body

FieldTypeRequiredDescription
locationobjectYesObject with lat and lng number properties
threshold_mmnumberYesMinimum hail size in mm to trigger the alert
webhook_urlstringYesHTTPS URL to receive webhook POST requests

Response Example

{
  "data": {
    "id": "sub_8f7e6d5c4b3a",
    "status": "active",
    "location": { "lat": 39.7392, "lng": -104.9903 },
    "threshold_mm": 25,
    "webhook_url": "https://example.com/webhooks/hail",
    "created_at": "2026-02-28T14:30:00Z"
  }
}
GET /v1/alerts/{id}

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

Path Parameters

ParameterTypeRequiredDescription
idstringYesSubscription ID (e.g., sub_8f7e6d5c4b3a)

Response Example

{
  "data": {
    "id": "sub_8f7e6d5c4b3a",
    "status": "active",
    "threshold_mm": 25,
    "recent_alerts": [
      {
        "alert_id": "alt_1a2b3c",
        "triggered_at": "2026-02-27T21:15:00Z",
        "mesh_size_mm": 38,
        "storm_id": "ST-20260227-CO-0089"
      }
    ]
  }
}
DELETE /v1/alerts/{id}

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

Path Parameters

ParameterTypeRequiredDescription
idstringYesSubscription ID to cancel

Response Example

{
  "data": {
    "id": "sub_8f7e6d5c4b3a",
    "status": "cancelled",
    "cancelled_at": "2026-02-28T16:00:00Z"
  }
}

Location & Radar

GET /v1/locations/{id}/risk

Returns a comprehensive risk assessment for a saved location. Combines historical frequency, climatological trends, and recent storm activity into a single risk score.

Path Parameters

ParameterTypeRequiredDescription
idstringYesLocation ID from your account

Response Example

{
  "data": {
    "location_id": "loc_denver_01",
    "risk_score": 73,
    "annual_hail_days": 9.2,
    "trend": "increasing",
    "last_event": {
      "date": "2025-06-14",
      "max_size_mm": 44
    }
  }
}
GET /v1/radar/current

Returns current radar product URLs and metadata for a location. Supports reflectivity, velocity, and MESH (Maximum Estimated Size of Hail) products.

Query Parameters

ParameterTypeRequiredDescription
latnumberYesLatitude (-90 to 90)
lngnumberYesLongitude (-180 to 180)
productsstringNoComma-separated list: reflectivity, velocity, mesh. Default: all

Response Example

{
  "data": {
    "station": "KFTG",
    "products": [
      {
        "type": "reflectivity",
        "timestamp": "2026-02-28T18:40:12Z",
        "tile_url": "https://tiles.hailsentinel.com/..."
      },
      {
        "type": "mesh",
        "timestamp": "2026-02-28T18:40:12Z",
        "tile_url": "https://tiles.hailsentinel.com/..."
      }
    ]
  }
}

Webhooks & SDKs

Event-Driven Integration

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

Webhook Events

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.

Example Webhook Payload

{
  "event": "hail.detected",
  "timestamp": "2026-02-28T18:42:00Z",
  "data": {
    "subscription_id": "sub_8f7e6d5c4b3a",
    "storm_id": "ST-20260228-CO-0042",
    "mesh_size_mm": 32,
    "probability": 0.87,
    "coordinates": {
      "lat": 39.7412,
      "lng": -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>

Rate Limits by Plan

Plan Requests / min Requests / day Webhooks
Free 10 1,000 1
Pro 60 10,000 10
Business 300 100,000 100

Ready to Build?

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

Request API Key Join Early Access

Get Started

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 Contact Sales

Free tier available · Join the early access waitlist