Tomorrow.io LLM-Friendly Weather API Documentation

Overview

The Alerts API enables you to create, manage, and monitor weather alerts for automated notifications and monitoring. Alerts can be configured based on custom insights or lightning conditions, with flexible notification schedules and location-based monitoring capabilities.

Key Features

• Insight-based alerts: Create alerts based on custom weather insights and conditions
• Lightning alerts: Specialized lightning detection and alerting with configurable buffers
• Flexible notifications: Configure PRIOR, START, END, and PUBLISH notification types
• Location-based monitoring: Link alerts to specific locations for continuous monitoring
• Tag organization: Organize and filter alerts using custom tags
• Critical alert support: Mark alerts as critical for high-priority notifications

Alert Types:

• Insight alerts: Based on custom weather insights and conditions
• Lightning alerts: Specialized lightning detection with distance buffers
• SIGMETS alerts: Aviation weather hazard alerts

Authentication

All Alerts API endpoints require authentication using your Tomorrow.io API key. Include your API key as a query parameter in all requests.

Authentication Method: API Key (query parameter)
Parameter Name: apikey
Example: ?apikey=YOUR_API_KEY

List Alerts

https://api.tomorrow.io/v4/alerts

Request Parameters

Parameter	Type	Required	Description	Example
`apikey`	String	Required	Your Tomorrow.io API key for authentication	`YOUR_API_KEY`
`limit`	Number	Optional	Maximum number of alerts to return (default: 10, max: 100)	`20`
`offset`	Number	Optional	Number of alerts to skip for pagination (default: 0)	`10`
`tags`	Array<String>	Optional	Filter alerts by tags	`["weather", "critical"]`

Request Example

cURL RequestBASH
curl --request GET \
  --url 'https://api.tomorrow.io/v4/alerts?apikey=YOUR_API_KEY&limit=10' \
  --header 'Accept-Encoding: gzip, deflate'

Response Example

200 Success ResponseJSON
{
  "data": {
    "alerts": [
      {
        "id": "00714370-fd87-4915-848b-31c338dcc6d1",
        "accountId": "5b168c92a71af5d57e15eb52",
        "type": "lightning",
        "insight": "lightning",
        "name": "Lightning Alert Example",
        "mode": "location_based",
        "isActive": true,
        "createdAt": "2024-01-31T08:14:12.350Z",
        "updatedAt": "2024-07-30T17:58:46.106Z",
        "createdBy": "60c103ff92986e00071216b4",
        "updatedBy": "642fbfb784acdc45e4bde312",
        "notifications": [
          {
            "type": "PRIOR",
            "value": 30,
            "title": "Lightning Alert",
            "description": "Lightning detected within alert area"
          }
        ],
        "isIgnoreNotificationsSchedule": false,
        "isCritical": false,
        "lightningConfig": {
          "lightningType": [
            "C2G"
          ],
          "buffers": [
            0.6,
            5,
            10
          ],
          "distanceUnit": "mi",
          "ttl": 10
        },
        "tags": [
          "weather",
          "lightning"
        ]
      },
      {
        "id": "0ae57a7b-a4f6-4027-8255-e8d831e04bd3",
        "accountId": "5b168c92a71af5d57e15eb52",
        "type": "insight",
        "insight": "6d2a8f02-9ae6-4f87-9ea7-aa9f8e299a43",
        "name": "Weather Condition Alert",
        "mode": "location_based",
        "isActive": true,
        "createdAt": "2025-06-16T11:20:03.890Z",
        "updatedAt": "2025-06-16T12:59:46.927Z",
        "createdBy": "620a34d1fe4fa9000861d30f",
        "updatedBy": "620a34d1fe4fa9000861d30f",
        "notifications": [
          {
            "type": "PRIOR",
            "value": 15,
            "title": "Weather condition alert starting within 15 minutes",
            "description": "Weather conditions are expected to meet alert criteria"
          }
        ],
        "isIgnoreNotificationsSchedule": false,
        "isCritical": false,
        "tags": [
          "weather",
          "monitoring"
        ]
      }
    ]
  },
  "meta": {
    "totalItems": 143
  },
  "links": {
    "self": "/v4/alerts?limit=10&offset=0",
    "next": "/v4/alerts?limit=10&offset=10"
  }
}

Create an Alert

Create Alert

https://api.tomorrow.io/v4/alerts

Request Parameters

Parameter	Type	Required	Description	Example
`name`	String	Required	The name of the alert used for identification and notifications	`High Wind Alert`
`insight`	String	Required	The ID of the insight to monitor for this alert, or "lightning" for lightning alerts	`insight_id_123`
`notifications`	Array<Object>	Optional	Array of notification configurations for the alert	`[{"type": "PRIOR", "value": 30, "title": "Alert Title", "description": "Alert description"}]`
`tags`	Array<String>	Optional	Array of tags to categorize and organize the alert	`["weather", "safety"]`
`isCritical`	Boolean	Optional	Whether this alert is marked as critical (default: false)	`true`
`isIgnoreNotificationsSchedule`	Boolean	Optional	Whether to ignore notification schedules for this alert (default: false)	`false`
`lightningConfig`	Object	Optional	Configuration for lightning alerts (required when insight is "lightning")	`{"lightningType": ["C2G", "C2C"], "buffers": [0.6, 5, 10], "distanceUnit": "mi", "ttl": 10}`

Notification Types

• PRIOR: Notification sent before the condition starts (requires "value" in minutes)
• START: Notification sent when the condition begins
• END: Notification sent when the condition ends
• PUBLISH: Notification sent when the alert is published

Request Example

cURL RequestBASH
curl --request POST \
  --url 'https://api.tomorrow.io/v4/alerts?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "High Wind Alert",
    "insight": "insight_id_123",
    "notifications": [
      {
        "type": "PRIOR",
        "value": 30,
        "title": "High Wind Warning",
        "description": "High winds expected within 30 minutes"
      },
      {
        "type": "START",
        "title": "High Wind Alert Active",
        "description": "High wind conditions have begun"
      }
    ],
    "tags": ["weather", "wind"],
    "isCritical": true
  }'

Response Example

201 Created ResponseJSON
{
  "data": {
    "alert": {
      "id": "99973372-7cd8-431e-9c30-13d4f048da9f",
      "accountId": "5b168c92a71af5d57e15eb52",
      "type": "insight",
      "insight": "003cccdd-d088-4051-b432-6244e094c6b1",
      "name": "LLM Docs Test Alert",
      "mode": "location_based",
      "isActive": true,
      "createdAt": "2025-07-07T04:48:58.883Z",
      "updatedAt": "2025-07-07T04:48:58.883Z",
      "createdBy": "5fbe2f3fa263600f64376da7",
      "updatedBy": "5fbe2f3fa263600f64376da7",
      "notifications": [
        {
          "type": "PRIOR",
          "value": 30,
          "title": "Test Alert",
          "description": "Test alert for documentation"
        }
      ],
      "isIgnoreNotificationsSchedule": false,
      "isCritical": false,
      "config": {},
      "tags": []
    }
  }
}

Retrieve an Alert

Retrieve Alert

https://api.tomorrow.io/v4/alerts/{alertId}

Request Parameters

Parameter	Type	Required	Description	Example
`alertId`	String	Required	ID of the alert to retrieve	`alert_id_123`
`apikey`	String	Required	Your Tomorrow.io API key for authentication	`YOUR_API_KEY`

Request Example

cURL RequestBASH
curl --request GET \
  --url 'https://api.tomorrow.io/v4/alerts/alert_id_123?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate'

Response Example

200 Success ResponseJSON
{
  "data": {
    "alert": {
      "id": "99973372-7cd8-431e-9c30-13d4f048da9f",
      "accountId": "5b168c92a71af5d57e15eb52",
      "type": "insight",
      "insight": "003cccdd-d088-4051-b432-6244e094c6b1",
      "name": "LLM Docs Test Alert",
      "mode": "location_based",
      "isActive": true,
      "createdAt": "2025-07-07T04:48:58.883Z",
      "updatedAt": "2025-07-07T04:48:58.883Z",
      "createdBy": "5fbe2f3fa263600f64376da7",
      "updatedBy": "5fbe2f3fa263600f64376da7",
      "notifications": [
        {
          "type": "PRIOR",
          "value": 30,
          "title": "Test Alert",
          "description": "Test alert for documentation"
        }
      ],
      "isIgnoreNotificationsSchedule": false,
      "isCritical": false,
      "config": {}
    }
  }
}

Update an Alert

Update Alert

https://api.tomorrow.io/v4/alerts/{alertId}

Request Parameters

Parameter	Type	Required	Description	Example
`alertId`	String	Required	ID of the alert to update	`alert_id_123`
`name`	String	Optional	Updated name for the alert	`Updated High Wind Alert`
`notifications`	Array<Object>	Optional	Updated notification configurations	`[{"type": "PRIOR", "value": 15, "title": "Updated Alert", "description": "Updated description"}]`
`tags`	Array<String>	Optional	Updated tags for the alert	`["weather", "updated"]`
`isActive`	Boolean	Optional	Whether the alert is active	`true`
`isCritical`	Boolean	Optional	Whether this alert is marked as critical	`false`

Request Example

cURL RequestBASH
curl --request PUT \
  --url 'https://api.tomorrow.io/v4/alerts/alert_id_123?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated High Wind Alert",
    "notifications": [
      {
        "type": "PRIOR",
        "value": 15,
        "title": "Updated Wind Warning",
        "description": "High winds expected within 15 minutes"
      }
    ],
    "tags": ["weather", "wind", "updated"],
    "isCritical": false
  }'

Response Example

200 Success ResponseJSON
{
  "data": {
    "alert": {
      "id": "alert_id_123",
      "name": "Updated High Wind Alert",
      "type": "insight",
      "insight": "insight_id_123",
      "isActive": true,
      "updatedAt": "2025-07-07T05:00:00.000Z",
      "notifications": [
        {
          "type": "PRIOR",
          "value": 15,
          "title": "Updated Wind Warning",
          "description": "High winds expected within 15 minutes"
        }
      ],
      "tags": ["weather", "wind", "updated"],
      "isCritical": false
    }
  }
}

Delete an Alert

Delete Alert

https://api.tomorrow.io/v4/alerts/{alertId}

Warning

Deleting an alert will permanently remove it and stop all associated notifications. This action cannot be undone.

Request Parameters

Parameter	Type	Required	Description	Example
`alertId`	String	Required	ID of the alert to delete	`alert_id_123`
`apikey`	String	Required	Your Tomorrow.io API key for authentication	`YOUR_API_KEY`

Request Example

cURL RequestBASH
curl --request DELETE \
  --url 'https://api.tomorrow.io/v4/alerts/alert_id_123?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate'

Response Example

204 No Content ResponseJSON
{
  "message": "Alert deleted successfully"
}

Lightning Alerts

Lightning alerts are specialized alerts that monitor lightning activity within specified distance buffers. They use the insight value "lightning" and require additional configuration parameters.

Lightning Configuration

• lightningType: Array of lightning types to monitor (C2G: Cloud-to-Ground, C2C: Cloud-to-Cloud)
• buffers: Array of distance buffers in specified units (e.g., [0.6, 5, 10])
• distanceUnit: Unit for distance measurements ("mi" for miles, "km" for kilometers)
• ttl: Time to live for lightning strikes in minutes
• combined: Whether to combine multiple lightning types (optional)

Lightning Alert Example

Lightning Alert CreationBASH
curl --request POST \
  --url 'https://api.tomorrow.io/v4/alerts?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Lightning Detection Alert",
    "insight": "lightning",
    "notifications": [
      {
        "type": "START",
        "title": "Lightning Detected",
        "description": "Lightning activity detected within alert area"
      }
    ],
    "lightningConfig": {
      "lightningType": ["C2G", "C2C"],
      "buffers": [0.6, 5, 10],
      "distanceUnit": "mi",
      "ttl": 10,
      "combined": true
    },
    "tags": ["lightning", "safety"],
    "isCritical": true
  }'

Error Handling

The Alerts API uses standard HTTP status codes to indicate the success or failure of requests. Error responses include detailed information to help diagnose issues.

Common Error Codes

Status Code	Error Type	Description
400	Bad Request	Invalid request parameters or missing required fields
401	Unauthorized	Invalid or missing API key
404	Not Found	Alert or insight not found
429	Rate Limited	Too many requests, please slow down
500	Internal Server Error	Server error, please try again later

Error Response Example

400 Error ResponseJSON
{
  "code": 400001,
  "type": "Invalid Body Parameters",
  "message": "The entries provided as body parameters were not valid for the request. Fix parameters and try again: Insight with the id invalid_insight_id is not found"
}

Best Practices

Alert Configuration

• Use descriptive names for easy identification
• Configure appropriate notification timing
• Set critical flag for high-priority alerts
• Use tags for organization and filtering
• Test alerts before production deployment

Performance Optimization

• Use pagination for large alert lists
• Filter by tags to reduce response size
• Cache alert configurations when possible
• Monitor API rate limits
• Use appropriate TTL for lightning alerts

Notification Management

• Configure multiple notification types as needed
• Use PRIOR notifications for preparation time
• Set appropriate timing for PRIOR notifications
• Include clear, actionable descriptions
• Consider notification schedules for non-critical alerts

Lightning Alerts

• Choose appropriate lightning types (C2G/C2C)
• Configure multiple distance buffers
• Set appropriate TTL for your use case
• Use combined mode for comprehensive coverage
• Consider distance units for your region