# 请求与返回

每个接口是 /v1 下的一个路径，用同一套参数名，返回同一种格式，共 6 个部分：code、request_id、data、page、warnings、meta。

## 路径和方法

接口的路径就是把编号里的点换成斜杠：`tiktok.videos.search` 就是 `GET /v1/tiktok/videos/search`。读数据用 `GET`，参数放在查询串里。带 `ids` 或 `keywords` 的请求用 `POST`，参数放在 JSON 请求体里；所以一个既能单查又能批量的接口两种方法都收。

```bash
curl -G "https://api.dataxapi.com/v1/tiktok/videos/search" \
  --data-urlencode "query=space station" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY"
```

## 参数和请求头

同一个名字在每个接口上都是同一个意思，每个接口的页面列出它收哪些。接口不收的参数直接被拒：400 `invalid_params`，不执行，不扣费。

- `query`: 搜索词
- `id`: 路径里第一个资源的编号
- `url`: 对象的链接，可代替编号
- `username`: 账号名，可代替编号
- `ids`: 一次查多个编号
- `keywords`: 一次查多个词
- `sort`: 排序方式：`relevance`、`latest`、`popular`；每个接口列出自己收哪些
- `since`: 发布时间不早于
- `until`: 发布时间不晚于
- `published_within`: 发布时间在最近多久之内：`day`、`week`、`month`、`half_year`、`year`；每个接口列出自己收哪些
- `window`: 统计周期：`24h`、`7d`、`30d`、`90d`；每个接口列出自己收哪些
- `board`: 选哪个榜
- `type`: 内容形态
- `tab`: 平台界面上的分栏
- `lang`: 语言代码
- `region`: 国家或地区代码
- `cursor`: 上一页返回的游标
- `limit`: 每页条数
- `view`: 返回档位：`compact`、`standard`、`full`
- `fields`: 只要这些字段
- `include`: 顺带返回的部分

### 请求头

- `Authorization`: `Bearer` 加你的 Key，见[鉴权](https://dataxapi.com/zh/docs/authentication/)。
- `Idempotency-Key`: 让一次调用可以重发而不重复扣费，见[计费](https://dataxapi.com/zh/docs/billing/)。
- `X-Max-Price`: 这次调用最多扣多少，美元，十进制字符串。可能超过它的调用在执行前就被拒。
- `X-Source`: 你自己的来源标记（哪个产品、哪个任务）。
- `X-End-User`: 你自己的终端用户标记。

两个标记是 1 到 128 个可见的 ASCII 字符，不含空格。它们只记在用量里；不要放邮箱、手机号这类个人信息。

## 返回格式

**每次都有**

|  |  |  |
| --- | --- | --- |
| `code` | 文字 | 成功时是 `ok`；出错时是错误代码。 |
| `request_id` | 文字 | 这次调用的请求号，响应头 `X-Request-Id` 里也有。 |

**数据**

|  |  |  |
| --- | --- | --- |
| `data.item` | 对象 | 单个对象，返回一个对象的接口用它。 |
| `data.items` | 列表 | 一组对象，列表和批量用它。`item` 和 `items` 只会有一个。 |
| `data.missing` | 列表 | 只在批量时有：没取到的输入，各带原因。 |

**翻页**

|  |  |  |
| --- | --- | --- |
| `page.next_cursor` | 文字或 null | 传回去当 `cursor` 取下一页；没有下一页时是 `null`。 |
| `page.cursor_expires_at` | 时间 | 这个游标能用到什么时候。 |
| `page.has_more` | 是否 | 还有没有下一页。 |
| `page.returned` | 整数 | 这一页有几条。 |

**关于这次调用**

|  |  |  |
| --- | --- | --- |
| `warnings` | 列表 | 丢掉或截短了什么，每项有一个 `code`：`items_dropped`、`items_not_requested`、`fields_unparsed`、`text_truncated`。 |
| `meta.capability` | 文字 | 接口编号。 |
| `meta.result_status` | 文字 | `complete`（完整）、`partial`（批量里有没取到的）或 `empty`（空）。 |
| `meta.fetched_at` | 时间 | 数据是什么时候取到的。 |
| `meta.cached` | 是否 | 数据来自共享快照（榜单和热点）。 |
| `meta.replayed` | 是否 | 这是之前一次调用存下来的结果，这次没有新增扣费。 |
| `meta.unavailable` | 对象 | 这个接口给不了的字段，各带原因。 |
| `meta.billing` | 对象 | `amount`（扣了多少）、`currency`（货币）、`balance_after`（扣后余额）。 |

报错是另一个统一的结构，每个接口都一样，见[错误代码](https://dataxapi.com/zh/docs/errors/)。

## 字段没有值的四种情况

| 情况 | 怎么表示 |
| --- | --- |
| 这一条本来就没有这个值 | 字段是 `null`。 |
| 这个接口给不了 | 字段不出现，列在 `meta.unavailable` 里并写明原因。 |
| 当前档位不含这个字段 | 字段不出现；换一个更全的 `view`。 |
| 拿到了但没解析出来 | 字段不出现，`warnings` 里写明是哪一条的哪个字段。 |

## 档位和格式

- `compact`: 只给最常用的字段；去掉头像、封面这类长链接，长正文截到 500 个字符，并在 `warnings` 里写明。
- `standard`: 默认：全部标准字段。
- `full`: 再加上平台特有的字段（`ext`）和会过期的媒体地址。

三档价格一样。

- 时间是 ISO 8601 的 UTC 时间。
- 金额是十进制字符串，单位美元。
- 编号一律是字符串。
- 每种对象的字段在它自己的页面上，例如 [post](https://dataxapi.com/zh/docs/objects/post/)；整套接口的说明文件是 [openapi.json](https://dataxapi.com/openapi.json)。

## 重取一次结果

结果保留 24 小时，凭请求号可以再读，不扣费，还可以换档位。这个地址只收 `view` 和 `fields`；返回的就是那次调用的返回，`meta.replayed` 为 true，`amount` 为 0。

```bash
curl -G "https://api.dataxapi.com/v1/calls/{request_id}/result" \
  --data-urlencode "view=full" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY"
```

---

目录修订号 c48ce454ae6c4c65。 [网页版](https://dataxapi.com/zh/docs/requests/)