Documentation Index
Fetch the complete documentation index at: https://sdk.sleepcycle.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Cough Radar REST API provides geospatial coughing analytics, enabling health monitoring applications to display coughing heatmaps and retrieve classification levels (normal, elevated, high) for specific geographic locations.
A typical integration displays an interactive map with cough-intensity heatmap overlays, accompanied by a panel showing the current classification and historical trends for the selected region. To build this:
-
Use
/v1/tiles to get tile URLs for rendering heatmap overlays on your map. The response is compatible with standard map libraries like Google Maps, Apple Maps, and Mapbox.
-
Use
/v1/classifications to fetch the cough activity level (normal, elevated, high) and trend data for the user’s current view or location. Display the classification status and render the time series data in a graph.
Authentication
All API requests require authentication via the API-Key header. Your API key must have the coughRadar capability enabled.
Base URL
https://cough-radar-api.sdk.sleepcycle.com
Endpoints
POST /v1/tiles
Fetch available heatmap tile data for a date range. Returns tile metadata including URLs for rendering map overlays.
Request
curl -X POST https://cough-radar-api.sdk.sleepcycle.com/v1/tiles \
-H "Content-Type: application/json" \
-H "API-Key: your-api-key" \
-d '{
"date_interval_start": "2026-01-01T00:00:00+00:00",
"date_interval_end": "2026-02-01T00:00:00+00:00"
}'
| Field | Type | Required | Description |
|---|
date_interval_start | datetime | Yes | Start date (ISO 8601 with timezone) |
date_interval_end | datetime | Yes | End date (ISO 8601 with timezone) |
{
"name": "aabbbccc-1234-5678-9101-abcdefabcdef",
"tile_data": [
{"date": "2026-02-01T00:00:00+00:00", "date_string": "2026-02-01"}
],
"base_template_url": "https://{base-url}/aabbbccc-1234-5678-9101-abcdefabcdef",
"relative_tile_template_path": "{date_string}/tile_{x}_{y}_{z}.png",
"max_zoom": 10
}
| Field | Type | Description |
|---|
name | string | Tile set identifier |
tile_data | array | Available dates with tile data |
base_template_url | string | Base URL for tile images |
relative_tile_template_path | string | URL template for individual tiles |
max_zoom | integer | Maximum zoom level available |
POST /v1/classifications
Get coughing classification (normal, elevated, high) for a geographic location or bounding box on a specific date.
You can specify the location using either:
- coordinate - A single point. The API returns aggregated data for the surrounding area (approximately 200 km radius).
- bounding_box - A geographic rectangle. The API returns aggregated data for the specified region.
Request (with coordinate)
curl -X POST https://cough-radar-api.sdk.sleepcycle.com/v1/classifications \
-H "Content-Type: application/json" \
-H "API-Key: your-api-key" \
-d '{
"date": "2026-02-01T00:00:00+00:00",
"coordinate": {"latitude": 59.33, "longitude": 18.07}
}'
curl -X POST https://cough-radar-api.sdk.sleepcycle.com/v1/classifications \
-H "Content-Type: application/json" \
-H "API-Key: your-api-key" \
-d '{
"date": "2026-02-01T00:00:00+00:00",
"bounding_box": {
"latitude_min": 59.0,
"latitude_max": 60.0,
"longitude_min": 17.0,
"longitude_max": 18.0
}
}'
| Field | Type | Required | Description |
|---|
date | datetime | Yes | Date for classification (ISO 8601 with timezone) |
trend_number_of_days | integer | No | Days for trend calculation (default: 30) |
coordinate | object | No* | Single point location |
bounding_box | object | No* | Geographic bounding box |
coordinate or bounding_box must be provided.
Response (200 OK)
{
"classification": "normal",
"coughing_per_hour_average": 0.8,
"coughing_data_time_series": {
"date": ["2026-01-31T00:00:00+00:00", "2026-02-01T00:00:00+00:00"],
"cough_per_hour_average": [0.25, 0.45]
},
"elevated_threshold": 0.8,
"high_threshold": 1.2
}
| Field | Type | Description |
|---|
classification | string | Classification level (see Data Types) |
coughing_per_hour_average | float | Average coughs per hour |
coughing_data_time_series | object | Historical trend data |
elevated_threshold | float | Threshold for elevated classification |
high_threshold | float | Threshold for high classification |
Data Types
Classification Values
Classifications compare current cough levels against historical data from the same location over the past year:
| Value | Description |
|---|
normal | Cough levels are within the typical range for this location |
elevated | Cough levels are higher than usual, ranking in the top 25% of recorded levels over the past year |
high | Cough levels are very high, ranking in the top 10% of recorded levels over the past year |
not_enough_data | Insufficient data to accurately classify cough levels |
Coughing Data Time Series Object
Historical trend data for the requested location.
| Field | Type | Description |
|---|
date | array | List of dates (ISO 8601 with timezone) |
cough_per_hour_average | array | Average coughs per hour for each corresponding date |
Coordinate Object
| Field | Type | Range | Description |
|---|
latitude | float | -90 to 90 | Latitude in decimal degrees |
longitude | float | -180 to 180 | Longitude in decimal degrees |
Bounding Box Object
| Field | Type | Range | Description |
|---|
latitude_min | float | -90 to 90 | Southern boundary |
latitude_max | float | -90 to 90 | Northern boundary |
longitude_min | float | -180 to 180 | Western boundary |
longitude_max | float | -180 to 180 | Eastern boundary |
Error Codes
| Status Code | Description |
|---|
| 200 | Success |
| 401 | Missing or invalid API key |
| 403 | API key lacks coughRadar capability |
| 422 | Invalid request body (validation error) |
| 500 | Internal server error |
