### GET /v3/exp/walltapper

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/realtime_walltapper.html

获取指定经纬度坐标下的高精度气温实况数据。

```APIDOC
## GET /v3/exp/walltapper

### Description
获取指定经纬度坐标下的高精度气温实况数据。该数据结合地面观测实况和高精度高程数据，对气温进行地形外推得到。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/exp/walltapper

### Parameters
#### Query Parameters
- **token** (string) - Required - 开发者 Token
- **longitude** (float) - Required - 经度 (GCJ-02 坐标系)
- **latitude** (float) - Required - 纬度 (GCJ-02 坐标系)

### Request Example
curl "https://singer.caiyunhub.com/v3/exp/walltapper?token={token}&longitude=116.3883&latitude=39.9289"

### Response
#### Success Response (200)
- **varname** (string) - 变量名称
- **unit** (string) - 单位
- **longitude** (float) - 经度
- **latitude** (float) - 纬度
- **datetime** (string) - 时间戳
- **value** (float) - 气温数值

#### Response Example
{
  "varname": "temperature",
  "unit": "degC",
  "longitude": 116.3883,
  "latitude": 39.9289,
  "datetime": "2024-05-14T10:20:00+08:00",
  "value": 28.85
}
```

--------------------------------

### GET /v3/sea/wave

Source: https://docs.caiyunapp.com/weather-api/v3/sea/wave.html

获取指定位置的海浪预报数据。此接口为增值服务，仅供企业套餐开发者使用。

```APIDOC
## GET /v3/sea/wave

### Description
获取指定经纬度的海浪预报数据，包含风浪、涌浪及总海浪的详细参数。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/sea/wave

### Parameters
#### Query Parameters
- **token** (string) - Required - 开发者授权令牌
- **latitude** (float) - Required - 纬度
- **longitude** (float) - Required - 经度
- **hours** (integer) - Required - 预报时长（小时）

### Response
#### Success Response (200)
- **shww** (array) - 风浪有效波高 (m)
- **mpww** (array) - 风浪平均周期 (s)
- **wvdir** (array) - 风浪传播方向 (°)
- **shts_1** (array) - 初级涌浪有效波高 (m)
- **shts_2** (array) - 次级涌浪有效波高 (m)
- **shts_3** (array) - 三级涌浪有效波高 (m)
- **swdir_1** (array) - 初级涌浪传播方向 (°)
- **swdir_2** (array) - 次级涌浪传播方向 (°)
- **swdir_3** (array) - 三级涌浪传播方向 (°)
- **mpts_1** (array) - 初级涌波平均周期 (s)
- **mpts_2** (array) - 次级涌波平均周期 (s)
- **mpts_3** (array) - 三级涌波平均周期 (s)
- **swh** (array) - 总海浪有效波高 (m)
- **perpw** (array) - 初级浪平均周期 (s)
- **dirpw** (array) - 初级浪传播方向 (°)

### Response Example
{
  "shts_1": [9999, 0.06],
  "swh": [0.81, 0.8],
  "shww": [0.81, 0.8]
}
```

--------------------------------

### Python Signature Generation Example

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/alert.html

A Python implementation for generating the MD5 signature using the required parameters.

```python
import hashlib


def generate_sign(token, id, publish_time, nonce, server_time):
    # 拼接字符串
    data = f"{token}-{id}-{publish_time}-{nonce}-{server_time}"
    # 计算 MD5 签名
    sign = hashlib.md5(data.encode()).hexdigest()
    return sign


# 示例数据
token = "your_token"
id = "your_id"
publish_time = 1234567890
nonce = "your_nonce"
server_time = 9876543210

# 生成签名
sign = generate_sign(token, id, publish_time, nonce, server_time)
print(sign)
```

--------------------------------

### 调用高精度温度实况接口

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/realtime_walltapper.html

使用 cURL 发起 GET 请求获取指定经纬度的气温数据，需替换 token 参数。

```bash
curl "https://singer.caiyunhub.com/v3/exp/walltapper?token={token}&longitude=116.3883&latitude=39.9289"
```

--------------------------------

### 调用次季节预报接口

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/subseasonal.html

使用 cURL 发送 GET 请求获取指定经纬度的次季节预报数据。

```bash
curl "https://singer.caiyunhub.com/v3/subseasonal?token={token}&longitude=116.3883&latitude=39.9289&days=2"
```

--------------------------------

### GET /v3/alert/location

Source: https://docs.caiyunapp.com/weather-api/v3/alert/location.html

根据经纬度坐标查询当前位置的气象预警信息。

```APIDOC
## GET /v3/alert/location

### Description
查询指定经纬度位置的气象预警信息。该接口为增值服务，调用需消耗额度。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/alert/location

### Parameters
#### Query Parameters
- **token** (string) - Required - 认证令牌
- **longitude** (float) - Required - 经度
- **latitude** (float) - Required - 纬度

### Response
#### Success Response (200)
- **alerts** (array) - 预警记录列表

#### Response Example
{
  "alerts": [
    {
      "id": "ALERT_CN_31000041600000_20250811152835",
      "region_code": "CN",
      "area_code": "310000",
      "source": 1,
      "alert_type": 156110214,
      "publish_time": 1754896800,
      "color": {
        "red": 250,
        "green": 230,
        "alpha": { "value": 1 }
      },
      "data": [
        {
          "language_code": "zh-CN",
          "title": "上海中心气象台发布雷电黄色预警[Ⅲ级/较重]",
          "text": "上海中心气象台2025年08月11日15时20分发布雷电黄色预警...",
          "level": "yellow",
          "name": "雷电黄色预警"
        }
      ]
    }
  ]
}
```

--------------------------------

### GET https://singer.caiyunhub.com/v3/typhoon/realtime

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/cyclone.html

获取当前中国近海台风的实时数据及相关路径信息。

```APIDOC
## GET https://singer.caiyunhub.com/v3/typhoon/realtime

### Description
获取当前中国近海台风的实时数据、历史路径及预报信息。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/typhoon/realtime

### Parameters
#### Query Parameters
- **token** (string) - Required - 开发者访问令牌

### Response
#### Success Response (200)
- **typhoons** (array) - 台风列表信息

#### Response Example
{
  "typhoons": [
    {
      "id": "202208",
      "name": "米雷",
      "enname": "Meari",
      "active": true,
      "history": [
        {
          "time": 1660240800,
          "longitude": 135.9,
          "latitude": 29.5,
          "radius7": [200, 200, 130, 150],
          "moveSpeed": 19,
          "moveDirection": "北",
          "strong": 2,
          "pressure": 1000,
          "speed": 18,
          "power": 8
        }
      ]
    }
  ]
}
```

--------------------------------

### Request Authentication in Go

Source: https://docs.caiyunapp.com/weather-api/v3/auth.html

Constructs a signed GET request by sorting query parameters and setting required headers.

```go
	// 构建查询字符串（按字母排序）
	keys := make([]string, 0, len(query))
	for k := range query {
		keys = append(keys, k)
	}
	sort.Strings(keys)
	var queryParts []string
	for _, k := range keys {
		queryParts = append(queryParts, url.QueryEscape(k)+"="+url.QueryEscape(query[k]))
	}
	rawQuery := strings.Join(queryParts, "&")

	signature := sign(appKey, appSecret, "GET", path, nonce, timestamp, query)

	reqURL := fmt.Sprintf("https://api.caiyunapp.com%s?%s", path, rawQuery)
	req, _ := http.NewRequest("GET", reqURL, nil)
	req.Header.Set("x-cy-app-key", appKey) // v3 通过 header 传递 appKey
	req.Header.Set("x-cy-nonce", nonce)
	req.Header.Set("x-cy-timestamp", strconv.FormatInt(timestamp, 10))
	req.Header.Set("x-cy-signature", signature)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

--------------------------------

### 行政区划查询 API 请求示例

Source: https://docs.caiyunapp.com/weather-api/v3/cartography/reverse-admins.html

使用 curl 发送 GET 请求，需提供经度、纬度及认证 token。

```bash
curl "https://singer.caiyunhub.com/v3/cartography/reverse_admins?longitude={longitude}&latitude={latitude}&token={token}"
```

--------------------------------

### GET /v3/glow/location

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/glow.html

查询指定经纬度位置的朝霞与晚霞预报信息。

```APIDOC
## GET /v3/glow/location

### Description
获取指定经纬度位置的朝霞与晚霞预报数据。该接口属于增值服务，仅提供给企业套餐开发者。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/glow/location

### Parameters
#### Query Parameters
- **longitude** (number) - Required - 经度
- **latitude** (number) - Required - 纬度
- **token** (string) - Required - 认证令牌
- **image** (boolean) - Optional - 是否返回图层 URL，默认为 true。设置为 false 时不返回图层相关字段

### Response
#### Success Response (200)
- **bbox** (BBox) - 数据覆盖范围边界框（仅当 image=true 时返回）
- **evening** (GlowInfo) - 晚霞信息
- **morning** (GlowInfo) - 朝霞信息

#### Response Example
{
  "evening": {
    "probability": 22,
    "quality": 32,
    "start_time": 1766735488,
    "end_time": 1766747776,
    "publish_time": 1766700000,
    "predict_date": {
      "year": 2025,
      "month": 12,
      "day": 26
    }
  },
  "morning": {
    "probability": 0,
    "quality": 0,
    "start_time": 0,
    "end_time": 0,
    "publish_time": 1766656800,
    "predict_date": {
      "year": 2025,
      "month": 12,
      "day": 26
    }
  }
}
```

--------------------------------

### 调用百米风 API

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/upper.html

使用 cURL 发送 GET 请求获取指定经纬度的高空风速与风向数据。

```bash
curl "https://singer.caiyunhub.com/v3/upper/100m/wind?token={token}&longitude=116.3883&latitude=39.9289&hours=12"
```

--------------------------------

### 获取生活指数 API 请求示例

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/lifeindex.html

使用 cURL 发送 GET 请求以获取指定经纬度的生活指数数据。

```bash
curl "https://singer.caiyunhub.com/v3/lifeindex?token={token}&longitude=116.3883&latitude=39.9289&days=1&fields=1,2,3"
```

--------------------------------

### GET https://singer.caiyunhub.com/v3/sea/tide/by_port

Source: https://docs.caiyunapp.com/weather-api/v3/sea/tide.html

获取指定港口的潮汐预报数据，支持查询单个、多个或全部港口。

```APIDOC
## GET https://singer.caiyunhub.com/v3/sea/tide/by_port

### Description
获取指定港口的潮汐预报数据，支持查询单个、多个或全部港口。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/sea/tide/by_port

### Parameters
#### Query Parameters
- **token** (string) - Required - 认证令牌
- **ids** (string) - Required - 港口编号，支持单个、多个（逗号分隔）或 'all'
- **days** (int) - Optional - 天数，最多 7 天

### Response
#### Success Response (200)
- **tide** (array) - 潮汐预报数据列表
  - **id** (string) - 港口编号
  - **date** (string) - 日期
  - **tide** (int[]) - 潮高，共 24 个值，代表各整点时的潮高
  - **event_time** (string[]) - 事件时间点
  - **event_tide** (int[]) - 事件潮高
```

--------------------------------

### GET https://singer.caiyunhub.com/v3/nwc/china/nc/region_cut/{var_name}

Source: https://docs.caiyunapp.com/weather-api/v3/region-cut/nwc-grid.html

获取指定变量的中国区域数值模式预报网格裁切数据。

```APIDOC
## GET https://singer.caiyunhub.com/v3/nwc/china/nc/region_cut/{var_name}

### Description
获取指定变量的中国区域数值模式预报网格裁切数据。支持的变量包括 rain_0m (地面降水量) 和 t_2m (近地面 2m 处气温)。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/nwc/china/nc/region_cut/{var_name}

### Parameters
#### Path Parameters
- **var_name** (string) - Required - 变量名称 (rain_0m 或 t_2m)

#### Query Parameters
- **token** (string) - Required - 用户秘钥
- **province_id** (string) - Required - 省份 ID

### Response
#### Success Response (200)
- **province_id** (string) - 省份 ID
- **var_name** (string) - 变量名
- **batch_time** (string) - 起报时间
- **items** (list) - 数据列表
- **items.#.step** (int) - 预报步长
- **items.#.valid_time** (string) - 数据时间
- **items.#.url** (string) - 文件链接

#### Response Example
{
  "province_id": "54",
  "var_name": "rain_0m",
  "batch_time": "2024-09-18T12:00:00Z",
  "items": [
    {
      "step": 1,
      "valid_time": "2024-09-18T13:00:00Z",
      "url": "https://meteorology.caiyuncdn.com/nafp-warms9km/develop/nafp_nc_p/2024/202409/20240918/54/2024091812_01.rain_0m.nc?auth_key=..."
    }
  ]
}
```

--------------------------------

### GET https://singer.caiyunhub.com/v3/sea/tide/ports

Source: https://docs.caiyunapp.com/weather-api/v3/sea/tide.html

获取所有港口列表，支持通过区域代码 (adcode) 进行过滤。

```APIDOC
## GET https://singer.caiyunhub.com/v3/sea/tide/ports

### Description
获取所有港口列表，支持通过区域代码 (adcode) 进行过滤。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/sea/tide/ports

### Parameters
#### Query Parameters
- **token** (string) - Required - 认证令牌
- **adcode** (string) - Optional - 区域代码，支持前缀匹配

### Response
#### Success Response (200)
- **ports** (array) - 港口列表
  - **id** (string) - 港口编号
  - **name** (string) - 港口名称
  - **coordinates** (float[]) - 港口坐标
  - **adcode** (string) - 区域代码
```

--------------------------------

### GET /v3/aqi/forecast/nc

Source: https://docs.caiyunapp.com/weather-api/v3/aqi/forecast.html

Retrieves links to air quality forecast NetCDF (NC) files.

```APIDOC
## GET /v3/aqi/forecast/nc

### Description
Retrieves a list of available air quality forecast NC files.

### Method
GET

### Endpoint
http://singer.caiyunhub.com/v3/aqi/forecast/nc

### Parameters
#### Query Parameters
- **token** (string) - Required - Authentication token
- **limit** (int) - Optional - Limit of returned items, default 1, max 72

### Response
#### Success Response (200)
- **items** (list) - List of NC file records

#### Response Example
{
  "items": [
    {
      "start_ts": 1739854800,
      "start_time": "2025-02-18T05:00:00Z",
      "url": "..."
    }
  ]
}
```

--------------------------------

### Node.js HTTPS Request Example

Source: https://docs.caiyunapp.com/weather-api/v3/auth.html

A basic implementation of an HTTPS request using the native Node.js https module.

```javascript
const req = https.request(options, (res) => {
  let data = "";
  res.on("data", (chunk) => (data += chunk));
  res.on("end", () => console.log(JSON.parse(data)));
});
req.end();
```

--------------------------------

### Java API Request Signing and Execution

Source: https://docs.caiyunapp.com/weather-api/v3/auth.html

Demonstrates how to generate an HmacSHA256 signature and perform an authenticated GET request in Java.

```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Base64;
import java.util.Map;
import java.util.TreeMap;
import java.util.UUID;
import java.util.stream.Collectors;

public class ApiRequest {

    public static String sign(
        String appKey,
        String appSecret,
        String method,
        String path,
        String nonce,
        long timestamp,
        Map<String, String> query
    ) throws Exception {
        Map<String, String> sortedQuery = new TreeMap<>(query);
        String queryStr = sortedQuery.entrySet().stream()
            .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8)
                      + "="
                      + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));

        String stringToSign = String.join(":",
            method, path, queryStr, appKey, nonce, String.valueOf(timestamp));

        Mac hmac = Mac.getInstance("HmacSHA256");
        hmac.init(new SecretKeySpec(appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] signatureBytes = hmac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8));
        return Base64.getUrlEncoder().encodeToString(signatureBytes);
    }

    public static void main(String[] args) throws Exception {
        String appKey = "your_app_key";
        String appSecret = "your_app_secret";
        String path = "/v3/lifeindex";

        // query 为纯业务参数，不含 token
        Map<String, String> query = new TreeMap<>();
        query.put("longitude", "116.3883");
        query.put("latitude", "39.9289");
        query.put("days", "1");

        String nonce = UUID.randomUUID().toString();
        long timestamp = Instant.now().getEpochSecond();

        String signature = sign(appKey, appSecret, "GET", path, nonce, timestamp, query);

        String queryStr = query.entrySet().stream()
            .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8)
                      + "="
                      + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));

        URL url = new URL("https://api.caiyunapp.com" + path + "?" + queryStr);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");
        conn.setRequestProperty("x-cy-app-key", appKey); // v3 通过 header 传递 appKey
        conn.setRequestProperty("x-cy-nonce", nonce);
        conn.setRequestProperty("x-cy-timestamp", String.valueOf(timestamp));
        conn.setRequestProperty("x-cy-signature", signature);

        try (BufferedReader reader = new BufferedReader(
                new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) {
            reader.lines().forEach(System.out::println);
        }
    }
}
```

--------------------------------

### 查询气象预警信息

Source: https://docs.caiyunapp.com/weather-api/v3/alert/location.html

通过经纬度坐标调用气象预警接口，需提供有效的 token。

```bash
curl "https://singer.caiyunhub.com/v3/alert/location?token={token}&longitude=121.4457&latitude=31.2557"
```

--------------------------------

### GET /v3/subseasonal

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/subseasonal.html

获取指定经纬度位置的次季节预报数据。

```APIDOC
## GET /v3/subseasonal

### Description
获取指定经纬度位置的次季节预报数据。本接口属于增值服务，仅提供给企业套餐开发者。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/subseasonal

### Parameters
#### Query Parameters
- **token** (string) - Required - 认证令牌
- **longitude** (double) - Required - 经度
- **latitude** (double) - Required - 纬度
- **days** (integer) - Optional - 预报天数

### Response
#### Success Response (200)
- **data** (array) - 预报数据列表

#### Response Example
{
  "data": [
    {
      "date": "2022-09-22",
      "nlwrt": 117.73,
      "cvpr": 0.001,
      "lspr": 0.0011,
      "t_2m": -51.37,
      "t_max": -48.53,
      "t_min": -53,
      "mslp": 99774.12,
      "wind_dir": 245.52,
      "wind_speed": 37.04,
      "humidity": -13.54,
      "skycon": 1
    }
  ]
}
```

--------------------------------

### GET /v3/upper/100m/wind

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/upper.html

获取指定经纬度位置的百米风速与风向预测数据。

```APIDOC
## GET /v3/upper/100m/wind

### Description
获取指定经纬度位置的百米风速与风向预测数据。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/upper/100m/wind

### Parameters
#### Query Parameters
- **token** (string) - Required - 认证令牌
- **longitude** (float) - Required - 经度
- **latitude** (float) - Required - 纬度
- **hours** (integer) - Required - 预测时长（小时）

### Response
#### Success Response (200)
- **wind_speed** (array) - 风速 (m/s)
- **wind_dir** (array) - 风向 (°)

### Response Example
{
  "wind_speed": [16.445768, 16.845646, 17.08505, 18.425108, 16.571037, 14.829574, 14.013913, 13.929026, 13.725182, 13.621485, 13.535716, 14.157788],
  "wind_dir": [15.919834, 19.654032, 30.892246, 36.596878, 39.991135, 34.37655, 29.742472, 26.120895, 24.203035, 27.083088, 33.310173, 35.94807]
}
```

--------------------------------

### 多语言逆地理编码调用

Source: https://docs.caiyunapp.com/weather-api/v3/cartography/reverse-geocoding.html

通过设置 Accept-Language 请求头获取不同语言的地名信息。

```bash
curl "https://singer.caiyunhub.com/v3/cartography/reverse_geocoding?token=token&latitude=35.6845&longitude=139.8070" \
     -H 'Accept-Language: zh-CN'
```

```json
{
  "name": "森下五丁目",
  "address": "日本 东京都 江东区 森下五丁目"
}
```

```bash
curl "https://singer.caiyunhub.com/v3/cartography/reverse_geocoding?token=token&latitude=35.6845&longitude=139.8070" \
     -H 'Accept-Language: en-US'
```

```json
{
  "name": "Morishita 5",
  "address": "Morishita 5, Koto, Tokyo, Japan"
}
```

```bash
curl "https://singer.caiyunhub.com/v3/cartography/reverse_geocoding?token=token&latitude=40.8577&longitude=-73.928" \
    -H 'Accept-Language: zh-CN'
```

```json
{
  "name": "Manhattan Community Board 12",
  "address": "美国 纽约 曼哈顿 Manhattan Community Board 12"
}
```

--------------------------------

### GET /v3/nwc/china/nc

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/nwc.html

获取中国区域模式预报数据的下载链接列表，包含全变量批次下载地址及各单变量下载地址。

```APIDOC
## GET /v3/nwc/china/nc

### Description
获取中国区域模式预报数据的下载链接列表，包含全变量批次下载地址及各单变量下载地址。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/nwc/china/nc

### Parameters
#### Query Parameters
- **token** (string) - Required - 认证令牌

### Response
#### Success Response (200)
- **results** (array) - 预报数据列表
  - **start_time** (string) - 起报时间
  - **forecast_num** (string) - 预报的第几个小时数
  - **nc_url** (string) - 完整一个批次下载链接
  - **vars_nc_url** (array) - 单变量下载信息列表
    - **name** (string) - 变量名称
    - **url** (string) - 单变量下载链接

### Response Example
{
  "results": [
    {
      "start_time": "2022071812",
      "forecast_num": "00",
      "nc_url": "http://example.com/xxxx.nc",
      "vars_nc_url": [
        {
          "name": "ws_10m",
          "url": "http://example.com/yyyy.nc"
        }
      ]
    }
  ]
}
```

--------------------------------

### 查询港口列表

Source: https://docs.caiyunapp.com/weather-api/v3/sea/tide.html

通过 API 获取所有港口或根据 adcode 过滤特定区域的港口信息。

```bash
# 获取所有港口
curl "https://singer.caiyunhub.com/v3/sea/tide/ports?token={token}"

# 根据 adcode 过滤港口
curl "https://singer.caiyunhub.com/v3/sea/tide/ports?token={token}&adcode={adcode}"
```

--------------------------------

### 获取台风实时数据

Source: https://docs.caiyunapp.com/weather-api/v3/cyclone/typhoon.html

使用 cURL 请求台风实时数据接口，需在 URL 中提供有效的 token。

```bash
curl "https://singer.caiyunhub.com/v3/typhoon/realtime?token={token}"
```

--------------------------------

### 获取日出日落时间

Source: https://docs.caiyunapp.com/weather-api/v3/astronomy/sun.html

通过经纬度查询指定天数的日出日落及曙光昏影时间。

```bash
curl "https://singer.caiyunhub.com/v3/astro/sun?longitude=116&latitude=39&dailystart=-1&days=3&token={token}"
```

--------------------------------

### GET /v3/lifeindex

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/lifeindex.html

获取指定经纬度位置的生活指数数据。

```APIDOC
## GET /v3/lifeindex

### Description
获取指定经纬度位置的生活指数数据。该接口属于增值服务，仅提供给企业套餐开发者。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/lifeindex

### Parameters
#### Query Parameters
- **token** (string) - Required - 认证令牌
- **longitude** (float) - Required - 经度
- **latitude** (float) - Required - 纬度
- **days** (int) - Required - 天数，范围 [1, 15]
- **fields** (string) - Required - 指数类型枚举，如 "1,2,3" 或 "all"

### Response
#### Success Response (200)
- **data** (array) - 生活指数数据列表
  - **date** (string) - 日期
  - **lifeindex** (array) - 指定的生活指数项
    - **type** (int) - 生活指数类型
    - **level** (int) - 指数等级
    - **desc** (string) - 短文本描述
    - **detail** (string) - 长文本描述

#### Response Example
{
  "data": [
    {
      "date": "2022-09-30",
      "lifeindex": [
        { "type": 1, "level": 2, "desc": "舒适", "detail": "极少人需要开机" }
      ]
    }
  ]
}
```

--------------------------------

### 获取站点预报 NC 文件列表

Source: https://docs.caiyunapp.com/weather-api/v3/aqi/forecast.html

使用 cURL 请求获取站点预报的 NC 文件下载链接列表。

```bash
curl "http://singer.caiyunhub.com/v3/aqi/forecast/nc?token={token}&limit=1"
```

--------------------------------

### API 请求示例

Source: https://docs.caiyunapp.com/weather-api/v3/region-cut/radar-gray.html

包含实时任务、预报任务以及指定 init_time 的请求示例。

```text
https://singer.caiyunhub.com/v3/ud/radar_gray/realtime/150622?token=your_valid_token
```

```text
https://singer.caiyunhub.com/v3/ud/radar_gray/forecast/150622?token=your_valid_token
```

```text
https://singer.caiyunhub.com/v3/ud/radar_gray/realtime/150622?init_time=1751356200&token=your_valid_token
```

```text
https://singer.caiyunhub.com/v3/ud/radar_gray/forecast/150622?init_time=1751356200&token=your_valid_token
```

--------------------------------

### GET /v3/cartography/reverse_geocoding

Source: https://docs.caiyunapp.com/weather-api/v3/cartography/reverse-geocoding.html

根据经纬度坐标获取对应的地名信息。

```APIDOC
## GET /v3/cartography/reverse_geocoding

### Description
根据经纬度坐标获取对应的地名信息。支持全球大部分区域，中国区域返回省市区三级地名。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/cartography/reverse_geocoding

### Parameters
#### Query Parameters
- **token** (string) - Required - 认证令牌
- **longitude** (float) - Required - 经度
- **latitude** (float) - Required - 纬度

### Request Example
curl "https://singer.caiyunhub.com/v3/cartography/reverse_geocoding?token=token&latitude=39.9289&longitude=116.3883"

### Response
#### Success Response (200)
- **name** (string) - 地名
- **address** (string) - 详细地址

#### Response Example
{
  "name": "西城区",
  "address": "北京市 西城区"
}
```

--------------------------------

### GET /v3/cartography/reverse_admins

Source: https://docs.caiyunapp.com/weather-api/v3/cartography/reverse-admins.html

根据经纬度查询行政区划信息。

```APIDOC
## GET /v3/cartography/reverse_admins

### Description
根据提供的经纬度坐标查询中国大陆区域的行政区划信息。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/cartography/reverse_admins

### Parameters
#### Query Parameters
- **longitude** (float) - Required - 经度
- **latitude** (float) - Required - 纬度
- **token** (string) - Required - 认证令牌

### Response
#### Success Response (200)
- **admins** (array) - 行政区划列表
- **region_code** (string) - 区域代码

#### Response Example
{
  "admins": [
    {
      "name": "北京市",
      "code": "110000"
    },
    {
      "name": "北京城区",
      "code": "110100"
    },
    {
      "name": "西城区",
      "code": "110102"
    }
  ],
  "region_code": "CN"
}
```

--------------------------------

### 获取太阳高度角和方位角

Source: https://docs.caiyunapp.com/weather-api/v3/astronomy/sun.html

通过经纬度查询逐小时的太阳高度角和方位角数据。

```bash
curl "https://singer.caiyunhub.com/v3/astro/sun/location/?longitude=116&latitude=39&days=2&token={token}"
```

--------------------------------

### 查询朝晚霞数据

Source: https://docs.caiyunapp.com/weather-api/v3/meteorology/glow.html

通过经纬度获取朝晚霞预报信息。image 参数默认为 true，返回包含图层 URL 的完整数据。

```bash
curl "https://singer.caiyunhub.com/v3/glow/location?longitude=116&latitude=39&token={token}"
```

```bash
curl "https://singer.caiyunhub.com/v3/glow/location?longitude=116&latitude=39&token={token}&image=false"
```

--------------------------------

### GET /v3/ud/gfs_soil/region_cut/{area_id}

Source: https://docs.caiyunapp.com/weather-api/v3/region-cut/gfs-soil.html

获取指定区域的土壤温湿预测数据文件列表。

```APIDOC
## GET /v3/ud/gfs_soil/region_cut/{area_id}

### Description
获取指定区域的土壤温湿预测数据文件列表，返回包含变量名称及对应下载链接的 JSON 对象。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/ud/gfs_soil/region_cut/{area_id}?token={token}

### Parameters
#### Path Parameters
- **area_id** (int) - Required - 区域唯一标识符

#### Query Parameters
- **token** (string) - Required - 接口认证密钥（Token）

### Response
#### Success Response (200)
- **area_id** (string) - 请求区域 ID
- **batch_time** (string) - 批处理时间（ISO 8601 格式）
- **items** (array) - 土壤变量数据列表
  - **variable** (string) - 变量名称
  - **url** (string) - 数据文件下载链接（含认证密钥）

#### Response Example
{
  "area_id": "41",
  "batch_time": "2025-06-03T18:00:00Z",
  "items": [
    {
      "variable": "soill_0-10-40-100cm",
      "url": "http://foo.bar/.../soill_depthBelowLandLayer_0_3_192.nc?auth_key=..."
    }
  ]
}
```

--------------------------------

### 获取临近站点预报数据

Source: https://docs.caiyunapp.com/weather-api/v3/aqi/forecast.html

使用 cURL 请求获取指定经纬度的站点空气质量预报数据。

```bash
curl "https://singer.caiyunhub.com/v3/aqi/forecast/station?token={token}&longitude=116.3883&latitude=39.9289&hours=120"
```

--------------------------------

### GET /v3/ud/radar_gray/{task_type}/{area_id}

Source: https://docs.caiyunapp.com/weather-api/v3/region-cut/radar-gray.html

获取指定任务类型和区域的雷达灰度图数据。

```APIDOC
## GET /v3/ud/radar_gray/{task_type}/{area_id}

### Description
获取指定任务类型（实时或预报）和区域 ID 的雷达灰度图数据。该接口支持通过 init_time 参数指定批次时间。

### Method
GET

### Endpoint
https://singer.caiyunhub.com/v3/ud/radar_gray/{task_type}/{area_id}?token={token}

### Parameters
#### Path Parameters
- **task_type** (string) - Required - 任务类型，取值：realtime（实时）或 forecast（预报）
- **area_id** (string) - Required - 区域 ID

#### Query Parameters
- **token** (string) - Required - 认证令牌
- **init_time** (int) - Optional - 批次时间，必须为整 5 分钟的时间戳

### Response
#### Success Response (200)
- **task_type** (string) - 任务类型
- **init_time** (number) - 数据初始化时间戳
- **items** (array) - 切割图数据列表
  - **area_id** (string) - 区域 ID
  - **forecast_time** (number) - 数据对应的预报/实时时间戳
  - **bound** (array) - 地理范围经纬度边界 [左经度, 下纬度, 右经度, 上纬度]
  - **url** (string) - 灰度切割图图片 URL

#### Response Example
{
  "task_type": "realtime",
  "init_time": 1751347800,
  "items": [
    {
      "area_id": "150622",
      "forecast_time": 1751347800,
      "bound": [103.00350189208984, 36.007301330566406, 116.9884033203125, 42.002201080322266],
      "url": "http://meteorology.caiyuncdn.com/ud/radar_gray/prod/realtime/2025/07/01/150622/cnmap_precp_202507010530.png?auth_key=..."
    }
  ]
}
```

--------------------------------

### 基本逆地理编码调用

Source: https://docs.caiyunapp.com/weather-api/v3/cartography/reverse-geocoding.html

通过经纬度坐标查询地名信息的基本请求示例。

```bash
curl "https://singer.caiyunhub.com/v3/cartography/reverse_geocoding?token=token&latitude=39.9289&longitude=116.3883"
```

```json
{
  "name": "西城区",
  "address": "北京市 西城区"
}
```

--------------------------------

### Token Authentication Methods

Source: https://docs.caiyunapp.com/weather-api/v3/auth.html

Describes the two supported ways to provide a token for authentication: via Query parameters or the Authorization header.

```APIDOC
## Token Authentication

### Description
Users can authenticate requests using a token. Note that Token authentication carries a leakage risk; App Key & App Secret authentication is recommended instead.

### Authentication Methods
- **Query Parameter**: Pass the token via the `token` query parameter.
  `curl "https://example.com/xxxx?token={token}"`
- **Header Parameter**: Pass the token via the `Authorization` header using the Bearer scheme.
  `curl "https://example.com" -H 'Authorization: Bearer {token}'`
```

--------------------------------

### 获取港口潮汐预报

Source: https://docs.caiyunapp.com/weather-api/v3/sea/tide.html

根据港口 ID 和预报天数获取潮汐数据，支持单个、多个或全部港口查询。

```bash
# 默认 API 调用格式
curl "https://singer.caiyunhub.com/v3/sea/tide/by_port?ids=T016&token={token}&days={days}"

# 只获取部分港口潮汐预报数据
curl "https://singer.caiyunhub.com/v3/sea/tide/by_port?ids=a,b,c&token={token}&days=3"

# 获取全部港口的潮汐预报数据
curl "https://singer.caiyunhub.com/v3/sea/tide/by_port?ids=all&token={token}&days=3"
```

--------------------------------

### 获取海浪预报数据

Source: https://docs.caiyunapp.com/weather-api/v3/sea/wave.html

使用 cURL 请求海浪预报接口，需替换 token、经纬度及预报小时数。

```bash
curl "https://singer.caiyunhub.com/v3/sea/wave?token={token}&latitude={latitude}&longitude={longitude}&hours={hours}"
```

--------------------------------

### App Key & App Secret 请求示例

Source: https://docs.caiyunapp.com/weather-api/v3/auth.html

一个具体的 API 请求示例，展示了如何填充认证头。

```bash
curl -s -X GET "https://singer.caiyunhub.com/v3/lifeindex?latitude=39.9289&longitude=116.3883" \
  -H "x-cy-app-key: test_app_key" \
  -H "x-cy-nonce: req-236926224039666-90412" \
  -H "x-cy-timestamp: 1770367395" \
  -H "x-cy-signature: 4-UHRpnNqp6h1khB1hJJRE4QarWJZFeBgtDk8WruNEA="
```