跳转到主要内容

​
概览

Cough Radar REST API 提供地理空间咳嗽分析能力，使健康监测应用能够展示咳嗽热力图，并查询特定地理位置的分类等级（normal、elevated、high）。 典型的集成方式是显示一张交互式地图，叠加咳嗽强度热力图，并在面板中展示所选区域的当前分类和历史趋势。要构建该集成：
  1. 使用 /v1/tiles 获取用于在地图上渲染热力图叠加层的瓦片 URL。响应与 Google Maps、Apple Maps 和 Mapbox 等标准地图库兼容。
  2. 使用 /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_startdatetime是起始日期（含时区的 ISO 8601 格式）
date_interval_enddatetime是结束日期（含时区的 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
}
字段类型描述
namestring瓦片集标识符
tile_dataarray包含瓦片数据的可用日期
base_template_urlstring瓦片图片的基础 URL
relative_tile_template_pathstring单个瓦片的 URL 模板
max_zoominteger可用的最大缩放级别

​
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
    }
  }'
请求体
字段类型是否必填描述
datedatetime是用于分类的日期（含时区的 ISO 8601 格式）
trend_number_of_daysinteger否趋势计算所用的天数（默认值：30）
coordinateobject否*单点位置
bounding_boxobject否*地理边界框
*必须提供 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
}
字段类型描述
classificationstring分类等级（参见数据类型）
coughing_per_hour_averagefloat平均每小时咳嗽次数
coughing_data_time_seriesobject历史趋势数据
elevated_thresholdfloatelevated 分类的阈值
high_thresholdfloathigh 分类的阈值

​
数据类型

​
分类值

分类是将当前咳嗽水平与同一位置过去一年的历史数据进行比较得出：
值描述
normal咳嗽水平在该位置的典型范围内
elevated咳嗽水平高于通常情况，位于过去一年记录水平的前 25%
high咳嗽水平非常高，位于过去一年记录水平的前 10%
not_enough_data数据不足，无法准确分类咳嗽水平

​
Coughing Data Time Series 对象

请求位置的历史趋势数据。
字段类型描述
datearray日期列表（含时区的 ISO 8601 格式）
cough_per_hour_averagearray与每个日期对应的平均每小时咳嗽次数

​
Coordinate 对象

字段类型范围描述
latitudefloat-90 到 90十进制纬度
longitudefloat-180 到 180十进制经度

​
Bounding Box 对象

字段类型范围描述
latitude_minfloat-90 到 90南边界
latitude_maxfloat-90 到 90北边界
longitude_minfloat-180 到 180西边界
longitude_maxfloat-180 到 180东边界

​
错误代码

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