Skip to main content

​
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:
  1. 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.
  2. 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
FieldTypeRequiredDescription
date_interval_startdatetimeYesStart date (ISO 8601 with timezone)
date_interval_enddatetimeYesEnd 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
}
FieldTypeDescription
namestringTile set identifier
tile_dataarrayAvailable dates with tile data
base_template_urlstringBase URL for tile images
relative_tile_template_pathstringURL template for individual tiles
max_zoomintegerMaximum 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
FieldTypeRequiredDescription
datedatetimeYesDate for classification (ISO 8601 with timezone)
trend_number_of_daysintegerNoDays for trend calculation (default: 30)
coordinateobjectNo*Single point location
bounding_boxobjectNo*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
}
FieldTypeDescription
classificationstringClassification level (see Data Types)
coughing_per_hour_averagefloatAverage coughs per hour
coughing_data_time_seriesobjectHistorical trend data
elevated_thresholdfloatThreshold for elevated classification
high_thresholdfloatThreshold for high classification

​
Data Types

​
Classification Values

Classifications compare current cough levels against historical data from the same location over the past year:
ValueDescription
normalCough levels are within the typical range for this location
elevatedCough levels are higher than usual, ranking in the top 25% of recorded levels over the past year
highCough levels are very high, ranking in the top 10% of recorded levels over the past year
not_enough_dataInsufficient data to accurately classify cough levels

​
Coughing Data Time Series Object

Historical trend data for the requested location.
FieldTypeDescription
datearrayList of dates (ISO 8601 with timezone)
cough_per_hour_averagearrayAverage coughs per hour for each corresponding date

​
Coordinate Object

FieldTypeRangeDescription
latitudefloat-90 to 90Latitude in decimal degrees
longitudefloat-180 to 180Longitude in decimal degrees

​
Bounding Box Object

FieldTypeRangeDescription
latitude_minfloat-90 to 90Southern boundary
latitude_maxfloat-90 to 90Northern boundary
longitude_minfloat-180 to 180Western boundary
longitude_maxfloat-180 to 180Eastern boundary

​
Error Codes

Status CodeDescription
200Success
401Missing or invalid API key
403API key lacks coughRadar capability
422Invalid request body (validation error)
500Internal server error