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

> 用于健康监测的地理空间咳嗽分析 API

## 概览

Cough Radar REST API 提供地理空间咳嗽分析能力，使健康监测应用能够展示咳嗽热力图，并查询特定地理位置的分类等级（normal、elevated、high）。

典型的集成方式是显示一张交互式地图，叠加咳嗽强度热力图，并在面板中展示所选区域的当前分类和历史趋势。要构建该集成：

1. 使用 [`/v1/tiles`](#post-%2Fv1%2Ftiles) 获取用于在地图上渲染热力图叠加层的瓦片 URL。响应与 Google Maps、Apple Maps 和 Mapbox 等标准地图库兼容。

2. 使用 [`/v1/classifications`](#post-%2Fv1%2Fclassifications) 获取用户当前视图或位置的咳嗽活动等级（normal、elevated、high）以及趋势数据。展示分类状态并以图表形式渲染时间序列数据。

## 身份验证

所有 API 请求都需要通过 `API-Key` 请求头进行身份验证。您的 API 密钥必须启用 `coughRadar` 功能。

```
API-Key: your-api-key
```

## 基础 URL

```
https://cough-radar-api.sdk.sleepcycle.com
```

## 端点

### POST /v1/tiles

获取指定日期范围内可用的热力图瓦片数据。返回包含用于渲染地图叠加层 URL 在内的瓦片元数据。

**请求**

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

**请求体**

| 字段                    | 类型       | 是否必填 | 描述                     |
| --------------------- | -------- | ---- | ---------------------- |
| `date_interval_start` | datetime | 是    | 起始日期（含时区的 ISO 8601 格式） |
| `date_interval_end`   | datetime | 是    | 结束日期（含时区的 ISO 8601 格式） |

**响应（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
}
```

| 字段                            | 类型      | 描述           |
| ----------------------------- | ------- | ------------ |
| `name`                        | string  | 瓦片集标识符       |
| `tile_data`                   | array   | 包含瓦片数据的可用日期  |
| `base_template_url`           | string  | 瓦片图片的基础 URL  |
| `relative_tile_template_path` | string  | 单个瓦片的 URL 模板 |
| `max_zoom`                    | integer | 可用的最大缩放级别    |

***

### POST /v1/classifications

获取指定日期下某地理位置或边界框的咳嗽分类（normal、elevated、high）。

可使用以下两种方式之一来指定位置：

* **coordinate** - 单个点。API 将返回该点周围区域（约 200 公里半径）的聚合数据。
* **bounding\_box** - 地理矩形区域。API 将返回该指定区域的聚合数据。

**请求（使用 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}
  }'
```

**请求（使用 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
    }
  }'
```

**请求体**

| 字段                     | 类型       | 是否必填 | 描述                        |
| ---------------------- | -------- | ---- | ------------------------- |
| `date`                 | datetime | 是    | 用于分类的日期（含时区的 ISO 8601 格式） |
| `trend_number_of_days` | integer  | 否    | 趋势计算所用的天数（默认值：30）         |
| `coordinate`           | object   | 否\*  | 单点位置                      |
| `bounding_box`         | object   | 否\*  | 地理边界框                     |

\*必须提供 `coordinate` 或 `bounding_box` 之一。

**响应（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
}
```

| 字段                          | 类型     | 描述             |
| --------------------------- | ------ | -------------- |
| `classification`            | string | 分类等级（参见数据类型）   |
| `coughing_per_hour_average` | float  | 平均每小时咳嗽次数      |
| `coughing_data_time_series` | object | 历史趋势数据         |
| `elevated_threshold`        | float  | elevated 分类的阈值 |
| `high_threshold`            | float  | high 分类的阈值     |

***

## 数据类型

### 分类值

分类是将当前咳嗽水平与同一位置过去一年的历史数据进行比较得出：

| 值                 | 描述                          |
| ----------------- | --------------------------- |
| `normal`          | 咳嗽水平在该位置的典型范围内              |
| `elevated`        | 咳嗽水平高于通常情况，位于过去一年记录水平的前 25% |
| `high`            | 咳嗽水平非常高，位于过去一年记录水平的前 10%    |
| `not_enough_data` | 数据不足，无法准确分类咳嗽水平             |

### Coughing Data Time Series 对象

请求位置的历史趋势数据。

| 字段                       | 类型    | 描述                     |
| ------------------------ | ----- | ---------------------- |
| `date`                   | array | 日期列表（含时区的 ISO 8601 格式） |
| `cough_per_hour_average` | array | 与每个日期对应的平均每小时咳嗽次数      |

### Coordinate 对象

| 字段          | 类型    | 范围         | 描述    |
| ----------- | ----- | ---------- | ----- |
| `latitude`  | float | -90 到 90   | 十进制纬度 |
| `longitude` | float | -180 到 180 | 十进制经度 |

### Bounding Box 对象

| 字段              | 类型    | 范围         | 描述  |
| --------------- | ----- | ---------- | --- |
| `latitude_min`  | float | -90 到 90   | 南边界 |
| `latitude_max`  | float | -90 到 90   | 北边界 |
| `longitude_min` | float | -180 到 180 | 西边界 |
| `longitude_max` | float | -180 到 180 | 东边界 |

***

## 错误代码

| 状态码 | 描述                       |
| --- | ------------------------ |
| 200 | 成功                       |
| 401 | 缺少或无效的 API 密钥            |
| 403 | API 密钥缺少 `coughRadar` 功能 |
| 422 | 请求体无效（验证错误）              |
| 500 | 服务器内部错误                  |