API docs by Redocly

Weather API (1.2.1)

Download OpenAPI specification:

E-mail: support@rainbow.ai

Overview

The Weather API provides accurate, real-time and forecasted weather data for various locations worldwide. It is designed to offer high-resolution weather data, including minute-by-minute and hourly forecasts, precipitation maps, and notifications.

This API is useful for applications that require detailed weather insights, such as mobile apps, travel planners, outdoor activity organizers, and emergency response systems.

Features

  • Weather Forecasting: Access forecasts for up to 24 hours, including temperature, humidity, wind speed, and UV index.
  • Minute-by-Minute Precipitation: Get high resolution precipitation data for the next 4 hours.
  • Hourly Forecast: Retrieve weather parameters such as temperature, pressure, wind speed, and visibility.
  • Map Tiles: Generate precipitation map tiles at various zoom levels.
  • Notifications: Subscribe to weather alerts and updates.

Authentication

  • All requests must include an authentication token.
  • The token is passed as a query parameter in every request:
    ?token=YOUR_API_KEY
  • If the token is missing or invalid, the API will return a 401 Unauthorized response.

Notification Service

The Weather API provides a powerful notification service that allows users to receive real-time alerts about weather changes in specified locations. This service ensures that applications can proactively notify users about significant weather conditions without the need for continuous polling.

How It Works

  • Users subscribe to weather notifications for specific locations
  • Locations are fully anonymized - only coordinate-based weather data is stored, without any personally identifiable information
  • The API monitors weather changes in the subscribed locations and sends notifications when significant events occur

To ensure secure communication, each service instance must obtain a unique WEATHER_NOTIFICATIONS_SECRET during the registration process. This secret key is required to authenticate and verify webhook requests using HMAC-SHA512 signatures.

How to Get WEATHER_NOTIFICATIONS_SECRET

Register for the Weather Notification Service

  • During registration, the system generates a unique secret key for your service instance
  • This key is securely assigned and must be used for signing and verifying API requests

Securely Store the Secret

  • The WEATHER_NOTIFICATIONS_SECRET should be stored in a secure environment, such as:
    • Environment variables
    • Secure vaults (e.g., AWS Secrets Manager, HashiCorp Vault)
  • It must not be exposed in client-side code, logs, or public repositories

Tiles API

API of the weather map

Map snapshot

Returns the most recent weather map snapshot

Responses

Response samples

Content type
application/json
{
  • "snapshot": 1737570600
}

Map tile with precipitations

This endpoint provides precipitation map tiles in PNG format, designed for use with common mapping services.

Tiles are PNG image files optimized for web mapping applications. They are generated using the Web Mercator projection (EPSG:3857), ensuring compatibility with popular mapping SDKs, including:

  • Mapbox
  • Google Maps
  • Leaflet
  • OpenLayers
  • Cesium
  • and others

Tiles are requested based on the standard XYZ tile system, allowing seamless integration into existing mapping applications.

path Parameters
snapshot
required
integer <int64> (Timestamp)
Examples: 1737570600

Snapshot of the weather map

forecast_time
required
integer

Forecast offset in seconds. Have to be a value >= 0. Currently available in range [0; 14400] (maximum 4 hours). Values are available with 600 seconds (10 minutes) step

zoom
required
integer

Zoom level [0 - 7]. For zoom level > 7 returns 404

tile_x
required
integer

x coordinate of a tile. In rage [0; 2^zoom]

tile_y
required
integer

y coordinate of a tile. In rage [0; 2^zoom]

query Parameters
color
integer

Index of color pallete:

  • 0 - Rainbow color schema
  • 1 - TWC color schema

Default color schema is 0

no_coverage
boolean

Flag to disable coverage mask

Responses

Response samples

Content type
image/png
image

Forecast API

API of the weather forecast

Check coverage for 24 hours weather forecast

This endpoint allows to check whether 24-hour weather forecast data is available for a given location.

path Parameters
longitude
required
number (Longitude)
Examples: 21.0065536398819

Longitude coordinate of the location for check

latitude
required
number (Latitude)
Examples: 52.23289409654632

Latitude coordinate of the location for check

Responses

Response samples

Content type
application/json
{
  • "snapshot": 1737570600,
  • "longitude": 21.0065536398819,
  • "latitude": 52.23289409654632,
  • "forecast": {
    • "minute": [
      • {
        • "timestampBegin": 1737570600,
        • "timestampEnd": 1737570660,
        • "precipRate": 1.42,
        • "precipType": "snow"
        }
      ],
    • "hourly": [
      • {
        • "timestampBegin": 1737568800,
        • "timestampEnd": 1737572400,
        • "temperature": -6.2,
        • "temperatureFeelsLike": -4.1,
        • "temperatureDewPoint": 12,
        • "uvIndex": 2,
        • "humidity": 39.5,
        • "pressure": 1050,
        • "windSpeed": 5.4,
        • "windDirection": 42,
        • "condition": "snow",
        • "visibility": 120
        }
      ]
    }
}

Weather forecast for 24 hours

This endpoint provides a detailed 24-hour weather forecast for a given location based on geographic coordinates (latitude & longitude).

The forecast includes:

  • Minute-by-minute precipitation for the next 4 hours.
  • Hourly forecast for temperature, pressure, wind speed, humidity, UV index, and other meteorological parameters.

Use Cases

  • Weather apps providing detailed short-term forecasts
  • Logistics & transportation companies planning routes
  • Outdoor activity planning, such as hiking, sports, and events

Data Coverage

  • The API supports global locations but may return 404 if weather data is unavailable in a specific area.
path Parameters
longitude
required
number (Longitude)
Examples: 21.0065536398819

Longitude coordinate of the location for which the forecast is requested

latitude
required
number (Latitude)
Examples: 52.23289409654632

Latitude coordinate of the location for which the forecast is requested

Responses

Response samples

Content type
application/json
{
  • "snapshot": 1737570600,
  • "longitude": 21.0065536398819,
  • "latitude": 52.23289409654632,
  • "forecast": {
    • "minute": [
      • {
        • "timestampBegin": 1737570600,
        • "timestampEnd": 1737570660,
        • "precipRate": 1.42,
        • "precipType": "snow"
        }
      ],
    • "hourly": [
      • {
        • "timestampBegin": 1737568800,
        • "timestampEnd": 1737572400,
        • "temperature": -6.2,
        • "temperatureFeelsLike": -4.1,
        • "temperatureDewPoint": 12,
        • "uvIndex": 2,
        • "humidity": 39.5,
        • "pressure": 1050,
        • "windSpeed": 5.4,
        • "windDirection": 42,
        • "condition": "snow",
        • "visibility": 120
        }
      ]
    }
}

Notification API

API of the weather notification service

Create or update a weather notification session for a point

This endpoint allows clients to create or update a weather notification session for tracking weather changes at a specified location.

When called with a new sessionId (UUID), this endpoint creates a new session for weather notifications

When an existing sessionId is provided, the session is updated with the latest location or notification settings. This should be used when the location of an object (e.g., a moving user, vehicle, or asset) has changed.

Use Cases

  • A mobile app tracking weather conditions for a moving user
  • A logistics system monitoring weather at a vehicle's current location
  • An outdoor event organizer updating weather alerts based on changing coordinates
Request Body schema: application/json
apiVersion
integer (ApiVersion)

API version used by the client. Ensures compatibility between input/output formats and the API's response structure. Used to manage changes in request and response formats across different versions.

sessionId
string (SessionId)

UUID (Version 4) of the session. Must conform to the RFC 4122 UUID format

object (Location)

Location to track weather changes for notifications

longitude
number (Longitude)

Longitude coordinate

latitude
number (Latitude)

Latitude coordinate

object (NotificationSettings)
advanceTime
integer <int64>

Specifies the maximum time in seconds before an event occurs when the notification should be sent to the user

Responses

Request samples

Content type
application/json
{
  • "apiVersion": 1,
  • "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  • "location": {
    • "longitude": 21.0065536398819,
    • "latitude": 52.23289409654632
    },
  • "settings": {
    • "advanceTime": 3600
    }
}

Response samples

Content type
application/json
{
  • "message": "Error message"
}

Create or update a weather notification session for geojson

This endpoint allows to create or update a weather notification session for tracking weather changes at one or multiple specified locations.

When called with a new sessionId (UUID), this endpoint creates a new session for weather notifications.

When an existing sessionId is provided, the session is updated with the latest location(s) or notification settings. This should be used when the location of an object (e.g., a moving user, vehicle, or asset) has changed.

The API supports multiple locations (N points) using a GeoJSON FeatureCollection. Weather conditions will be tracked for all provided points.

Use Cases

  • A mobile app tracking weather conditions for multiple moving users
  • A logistics system monitoring weather at different vehicle locations
  • An outdoor event organizer updating weather alerts for multiple event sites

Supported GeoJSON Format

  • The API currently supports only Point geometries in a GeoJSON FeatureCollection format
  • Each point must have a unique id with a maximum length of 128 symbols
Request Body schema: application/json
apiVersion
integer (ApiVersion)

API version used by the client. Ensures compatibility between input/output formats and the API's response structure. Used to manage changes in request and response formats across different versions.

sessionId
string (SessionId)

UUID (Version 4) of the session. Must conform to the RFC 4122 UUID format

geojson
object

GeoJSON object representing the location to track weather changes for notifications. Currently, only Point geometries are supported.

object (NotificationSettings)
advanceTime
integer <int64>

Specifies the maximum time in seconds before an event occurs when the notification should be sent to the user

Responses

Request samples

Content type
application/json
{
  • "apiVersion": 1,
  • "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  • "geojson": {
    • "type": "FeatureCollection",
    • "features": [
      • {
        • "type": "Feature",
        • "properties": { },
        • "geometry": {
          • "type": "Point",
          • "id": "unique point id",
          • "coordinates": [
            • 21.1462,
            • 52.28262
            ]
          }
        }
      ]
    },
  • "settings": {
    • "advanceTime": 3600
    }
}

Response samples

Content type
application/json
{
  • "message": "Error message"
}

Webhook for receiving weather notifications

This webhook will be called by the Weather API when a weather event occurs for a subscribed session.

  • The client must provide a webhook URL (WEATHER_API_NOTIFICATIONS_WEBHOOK_URL) during the registration in the notification service
  • When a relevant weather event is detected, the Weather API sends an HTTP POST request to the registered webhook URL
  • The webhook payload contains details about the weather event, including location, event type, and additional meteorological data
query Parameters
salt
required
string

A special salt string used for computing a security hash

sig
required
string

Security signature for request verification.

  • Computed as an HMAC-SHA512 hash of a concatenated string:
    HMAC(SALT + '\n' + sessionId, WEATHER_NOTIFICATIONS_SECRET)

Request Verification Steps

  • Recompute the HMAC-SHA512 signature using the known WEATHER_NOTIFICATIONS_SECRET
  • Compare the computed signature with the received sig:
    • If they match - ✅ The request is valid.
    • If they don’t match - ❌ Reject the request (401 Unauthorized).

Signature Computation Example (Python)

import hashlib
import hmac

secret = b"WEATHER_NOTIFICATIONS_SECRET"
salt = "random-generated-salt"
session_id = "550e8400-e29b-41d4-a716-446655440000"

message = f"{salt}\n{session_id}".encode()
signature = hmac.new(secret, message, hashlib.sha512).hexdigest()

print(signature)  # Send this as the "sig" parameter
Request Body schema: application/json
apiVersion
integer (ApiVersion)

API version used by the client. Ensures compatibility between input/output formats and the API's response structure. Used to manage changes in request and response formats across different versions.

sessionId
string (SessionId)

UUID (Version 4) of the session. Must conform to the RFC 4122 UUID format

action
string
Enum: "session_start" "session_end" "notifications"
Array of WebHookNotificationPayload (objects) or WebHookSessionStartPayload (object) or WebHookSessionEndPayload (object)
One of
Array
pointId
string

Unique identifier of the point for which the event was generated. This ID corresponds to the specific location within the GeoJSON dataset.

eventType
string
Enum: "precipitation" "storm"
WebHookNotificationPrecipEvent (object)
One of
duration
integer

Duration of the precipitation in seconds

is_confident
boolean

Indicates whether the notification is highly reliable.

  • If true, precipitation will occur with high certainty
  • If false, precipitation is likely to occur but may be missed due to forecast uncertainties

A false value is uncommon but may occur in cases of very light drizzle, where detection is challenging. This allows systems to determine whether such events should trigger notifications

intensity
string (PrecipIntensity)
Enum: "rain_drizzle" "rain_light" "rain_moderate" "rain_heavy" "rain_intense" "rain_extreme" "snow_light" "snow_moderate" "snow_heavy" "mix_light" "mix_moderate" "mix_heavy"

Classified precipitation intensity, indicating both the type and severity of precipitation.

Rain Intensities:

  • rain_drizzle - Very light rain with fine droplets
  • rain_light - Light rain with minimal impact
  • rain_moderate - Steady rain with moderate intensity
  • rain_heavy - Heavy rainfall that may affect visibility and outdoor activities
  • rain_intense - Intense rainfall, potentially leading to minor flooding
  • rain_extreme - Extreme rainfall, likely causing hazardous conditions

Snow Intensities:

  • snow_light - Light snowfall with minimal accumulation
  • snow_moderate - Moderate snowfall with possible accumulation
  • snow_heavy - Heavy snowfall, significantly impacting visibility and travel

Mixed Precipitation:

  • mix_light - Light mix of rain and snow or sleet
  • mix_moderate - Moderate mix of rain and snow, may create slippery conditions
  • mix_heavy - Heavy mix of precipitation, leading to hazardous conditions
object (Location)

The exact location where the event was detected.

The event payload includes precise coordinates because the object may have moved. This allows systems to decide whether to display the event or highlight its exact location on a map.

precipRate
number

Precipitation rate in mm/h

precipType
string
Enum: "rain" "snow" "mixed"

Precipitation type

status
string
Enum: "start" "end"

Indicates the status of the precipitation.

  • start - precipitation will begin at the specified location and time
  • end - precipitation will stop at the specified location and time
timestamp
integer <int64> (Timestamp)

UNIX timestamp (in seconds) indicating when the event is expected to occur

Responses

Request samples

Content type
application/json
{
  • "apiVersion": 1,
  • "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  • "action": "notifications",
  • "payload": [
    • {
      • "pointId": "string",
      • "eventType": "precipitation",
      • "event": {
        • "duration": 1500,
        • "is_confident": true,
        • "intensity": "snow_light",
        • "location": {
          • "longitude": 21.0065536398819,
          • "latitude": 52.23289409654632
          },
        • "precipRate": 1.42,
        • "precipType": "snow",
        • "status": "start",
        • "timestamp": 1737570600
        }
      }
    ]
}