> ## 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.

# Cough Radar API

> Geospatial coughing analytics API for health monitoring

## 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`](#post-%2Fv1%2Ftiles) 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`](#post-%2Fv1%2Fclassifications) 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**

```bash theme={null}
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)**

```json theme={null}
{
  "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)**

```bash theme={null}
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)**

```bash theme={null}
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)**

```json theme={null}
{
  "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                   |