Cough Radar API

概览

Cough Radar REST API 提供地理空间咳嗽分析能力，使健康监测应用能够展示咳嗽热力图，并查询特定地理位置的分类等级（normal、elevated、high）。典型的集成方式是显示一张交互式地图，叠加咳嗽强度热力图，并在面板中展示所选区域的当前分类和历史趋势。要构建该集成：

使用 /v1/tiles 获取用于在地图上渲染热力图叠加层的瓦片 URL。响应与 Google Maps、Apple Maps 和 Mapbox 等标准地图库兼容。
使用 /v1/classifications 获取用户当前视图或位置的咳嗽活动等级（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 在内的瓦片元数据。请求

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）

{
  "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）

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）

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）

{
  "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	服务器内部错误

入门

平台

REST API

版本说明

法律声明

概览

身份验证

基础 URL

端点

POST /v1/tiles

POST /v1/classifications

数据类型

分类值

Coughing Data Time Series 对象

Coordinate 对象

Bounding Box 对象

错误代码

​概览

​身份验证

​基础 URL

​端点

​POST /v1/tiles

​POST /v1/classifications

​数据类型

​分类值

​Coughing Data Time Series 对象

​Coordinate 对象

​Bounding Box 对象

​错误代码

概览

身份验证

基础 URL

端点

POST /v1/tiles

POST /v1/classifications

数据类型

分类值

Coughing Data Time Series 对象

Coordinate 对象

Bounding Box 对象

错误代码