Cough Radar API

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.

API-Key: your-api-key

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"
  }'

Request Body

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)

Response (200 OK)

{
  "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}
  }'

Request (with bounding box)

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
    }
  }'

Request Body

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

*Either 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

Getting Started

Platforms

REST APIs

Release Notes

Legal

Overview

Authentication

Base URL

Endpoints

POST /v1/tiles

POST /v1/classifications

Data Types

Classification Values

Coughing Data Time Series Object

Coordinate Object

Bounding Box Object

Error Codes

​Overview

​Authentication

​Base URL

​Endpoints

​POST /v1/tiles

​POST /v1/classifications

​Data Types

​Classification Values

​Coughing Data Time Series Object

​Coordinate Object

​Bounding Box Object

​Error Codes

Overview

Authentication

Base URL

Endpoints

POST /v1/tiles

POST /v1/classifications

Data Types

Classification Values

Coughing Data Time Series Object

Coordinate Object

Bounding Box Object

Error Codes