> For the complete documentation index, see [llms.txt](https://docscn.jkidata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docscn.jkidata.com/xin-wen-shu-ju/fan-hui-shu-ju-jie-gou-shuo-ming.md).

# 📥 返回数据结构说明

新闻接口返回 JSON 数据。成功响应包含请求状态、结果总数、新闻列表和下一页分页标识。

### 成功响应结构

```
{
  "status": "success",
  "totalResults": 100,
  "results": [],
  "nextPage": "NEXT_PAGE_TOKEN"
}
```

### 顶层字段

| 字段             | 类型            | 说明                       |
| -------------- | ------------- | ------------------------ |
| `status`       | string        | 请求状态，成功时为 `success`      |
| `totalResults` | number        | 符合查询条件的新闻总数              |
| `results`      | array         | 本次请求返回的新闻对象列表            |
| `nextPage`     | string / null | 下一页分页标识；没有下一页时可能为 `null` |

{% hint style="info" %}\
`totalResults` 表示符合条件的结果总数，不代表本次响应中 `results` 数组的长度。\
{% endhint %}

### 完整响应示例

```
{
  "status": "success",
  "totalResults": 2876,
  "results": [
    {
      "article_id": "example-article-id",
      "title": "Example financial market news",
      "link": "https://example.com/news/article",
      "keywords": [
        "NASDAQ",
        "stocks"
      ],
      "creator": [
        "Example Author"
      ],
      "video_url": null,
      "description": "Example news description.",
      "content": "Example news content.",
      "pubDate": "2026-08-30 10:30:00",
      "pubDateTZ": "UTC",
      "image_url": "https://example.com/image.jpg",
      "source_id": "example-source",
      "source_name": "Example Source",
      "source_url": "https://example.com",
      "source_icon": "https://example.com/icon.png",
      "source_priority": 100,
      "language": "english",
      "country": [
        "united states of america"
      ],
      "category": [
        "business"
      ],
      "ai_tag": null,
      "ai_region": null,
      "ai_org": null,
      "sentiment": "neutral",
      "sentiment_stats": {
        "positive": 0.2,
        "neutral": 0.7,
        "negative": 0.1
      },
      "duplicate": false
    }
  ],
  "nextPage": "NEXT_PAGE_TOKEN"
}
```

> 示例仅用于说明数据结构，不代表真实新闻或当前结果数量。

### 新闻对象字段

`results` 数组中的每个元素代表一条新闻。

#### 基础信息

| 字段            | 类型             | 说明         |
| ------------- | -------------- | ---------- |
| `article_id`  | string         | 新闻的唯一标识    |
| `title`       | string / null  | 新闻标题       |
| `link`        | string / null  | 新闻原文链接     |
| `description` | string / null  | 新闻摘要       |
| `content`     | string / null  | 新闻正文       |
| `keywords`    | array / null   | 新闻关键词列表    |
| `creator`     | array / null   | 作者或内容创建者列表 |
| `duplicate`   | boolean / null | 是否被识别为重复新闻 |

#### 发布时间

| 字段          | 类型            | 说明        |
| ----------- | ------------- | --------- |
| `pubDate`   | string / null | 新闻发布时间    |
| `pubDateTZ` | string / null | 发布时间对应的时区 |

日期示例：

```
2026-08-30 10:30:00
```

{% hint style="warning" %}\
不要直接假设 `pubDate` 使用本地时区。处理时间时应同时读取 `pubDateTZ`，并在客户端转换为需要的时区。\
{% endhint %}

#### 图片与视频

| 字段          | 类型            | 说明     |
| ----------- | ------------- | ------ |
| `image_url` | string / null | 新闻图片地址 |
| `video_url` | string / null | 新闻视频地址 |

图片和视频字段不保证存在。展示前应检查字段是否为有效 URL。

```
if (article.image_url) {
  console.log("新闻图片：", article.image_url);
}

if (article.video_url) {
  console.log("新闻视频：", article.video_url);
}
```

#### 新闻来源

| 字段                | 类型            | 说明        |
| ----------------- | ------------- | --------- |
| `source_id`       | string / null | 新闻来源的唯一标识 |
| `source_name`     | string / null | 新闻来源名称    |
| `source_url`      | string / null | 新闻来源网站    |
| `source_icon`     | string / null | 新闻来源图标    |
| `source_priority` | number / null | 新闻来源优先级   |

`source_priority` 可用于辅助排序，但不建议将其作为判断新闻真实性或重要性的唯一依据。

#### 语言、国家与分类

| 字段         | 类型            | 说明           |
| ---------- | ------------- | ------------ |
| `language` | string / null | 新闻内容语言       |
| `country`  | array / null  | 新闻关联的国家或地区列表 |
| `category` | array / null  | 新闻所属分类列表     |

`country` 和 `category` 可能包含多个值：

```
{
  "language": "english",
  "country": [
    "united states of america",
    "singapore"
  ],
  "category": [
    "business",
    "top"
  ]
}
```

因此，客户端应按数组处理，不能假设只有一个国家或分类。

#### AI 扩展字段

| 字段                | 类型                    | 说明         |
| ----------------- | --------------------- | ---------- |
| `ai_tag`          | array / string / null | AI 识别的新闻标签 |
| `ai_region`       | array / string / null | AI 识别的相关地区 |
| `ai_org`          | array / string / null | AI 识别的相关机构 |
| `sentiment`       | string / null         | 新闻情绪分类     |
| `sentiment_stats` | object / null         | 新闻情绪分析数据   |

AI 字段可能因新闻来源、语言或处理状态而缺失。

### 情绪字段

`sentiment` 可能返回：

| 值          | 说明 |
| ---------- | -- |
| `positive` | 正面 |
| `neutral`  | 中立 |
| `negative` | 负面 |

`sentiment_stats` 示例：

```
{
  "positive": 0.2,
  "neutral": 0.7,
  "negative": 0.1
}
```

| 字段         | 类型     | 说明        |
| ---------- | ------ | --------- |
| `positive` | number | 正面情绪占比或评分 |
| `neutral`  | number | 中立情绪占比或评分 |
| `negative` | number | 负面情绪占比或评分 |

{% hint style="warning" %}\
情绪分析结果由自动化模型生成，仅适合用作辅助参考，不应作为投资决策的唯一依据。\
{% endhint %}

### 正文说明

`content` 是否包含完整正文取决于请求参数、新闻来源和内容授权。

即使使用：

```
full_content=1
```

部分新闻的 `content` 仍可能为空、不完整或与摘要内容相同。客户端应准备以下降级展示顺序：

1. 优先展示 `content`。
2. `content` 为空时展示 `description`。
3. 正文和摘要都为空时，只展示 `title` 和原文链接。

#### JavaScript

```
const displayText =
  article.content ||
  article.description ||
  article.title ||
  "暂无内容";
```

#### Python

```
display_text = (
    article.get("content")
    or article.get("description")
    or article.get("title")
    or "暂无内容"
)
```

### 分页说明

当响应包含 `nextPage` 时，将该值作为下一次请求的 `page` 参数。

```
GET /latest?category=business&q=NASDAQ&page=NEXT_PAGE_TOKEN&key=YOUR_API_KEY
```

`nextPage` 必须原样传递：

```
const nextPage = result.nextPage;

if (nextPage) {
  params.set("page", nextPage);
}
```

{% hint style="info" %}\
翻页后应使用 `article_id` 对新闻进行去重。新闻源更新期间，不同页面的数据顺序可能发生变化。\
{% endhint %}

### 无结果响应

当没有符合条件的新闻时，`results` 可能返回空数组：

```
{
  "status": "success",
  "totalResults": 0,
  "results": [],
  "nextPage": null
}
```

客户端不应将空数组直接视为接口故障。

### 业务错误响应

部分错误可能仍通过 HTTP `200` 返回，因此必须检查 JSON 中的业务状态。

错误响应可能类似：

```
{
  "Cmd": "api",
  "State": -1,
  "Msg": "接口请求出错，请检查参数"
}
```

| 字段      | 类型     | 说明            |
| ------- | ------ | ------------- |
| `Cmd`   | string | 接口或命令标识       |
| `State` | number | 业务状态；负数通常表示失败 |
| `Msg`   | string | 错误原因说明        |

### 推荐判断方式

#### JavaScript

```
function validateNewsResponse(response, result) {
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  if (
    result.status === "error" ||
    (typeof result.State === "number" && result.State < 0)
  ) {
    throw new Error(
      result.message ||
      result.Msg ||
      "News API request failed"
    );
  }

  return result;
}
```

#### Python

```
def validate_news_response(response, result):
    response.raise_for_status()

    if (
        result.get("status") == "error"
        or result.get("State", 0) < 0
    ):
        raise RuntimeError(
            result.get("message")
            or result.get("Msg")
            or "News API request failed"
        )

    return result
```

### 数据处理建议

* 使用 `article_id` 作为新闻的主要唯一标识。
* `article_id` 缺失时，可使用 `link` 辅助去重。
* 所有可选字段都应兼容缺失、空字符串和 `null`。
* `keywords`、`creator`、`country` 和 `category` 应按数组处理。
* 不要依赖新闻在 `results` 中的固定顺序。
* 图片、视频和正文加载失败时，应提供降级展示。
* AI 标签与情绪分析仅作为辅助信息使用。