足球 API 与股票 API 接入教程

快速开始

HKJData 使用标准 HTTP API。完成注册后，把 API Key 放入请求头，即可读取足球和股票 JSON 数据。

STEP 1注册账号前往用户中心完成免费注册。

STEP 2生成 API Key密钥只在服务端安全保存和使用。

STEP 3发送请求选择足球或股票接口读取 JSON。

建议先调用足球 /live?priority=top 或股票 /symbols/search，确认鉴权和网络正常后再接入详情接口。

鉴权与 API Key

在请求头中使用 Bearer Token。请把密钥放在服务端环境变量中，不要提交到 Git，也不要嵌入公开网页或客户端包。

HTTP Header

Authorization: Bearer YOUR_API_KEY
Accept: application/json
User-Agent: YourProduct-HKJData/1.0

第一次请求

下面三个示例调用同一个足球实时接口。切换语言后替换 YOUR_API_KEY 即可运行。

cURL

curl "https://api.hkjdata.com/api/v1/football/live?priority=top"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Accept: application/json"

Python · requests

import os
import requests

base_url = os.environ["HKJDATA_BASE_URL"]
headers = {"Authorization": f"Bearer {os.environ['HKJDATA_API_KEY']}"}
response = requests.get(
    f"{base_url}/api/v1/football/live",
    params={"priority": "top"},
    headers=headers,
    timeout=10,
)
response.raise_for_status()
matches = response.json()

JavaScript · Node.js

const response = await fetch(
  `${process.env.HKJDATA_BASE_URL}/api/v1/football/live?priority=top`,
  { headers: { Authorization: `Bearer ${process.env.HKJDATA_API_KEY}` } }
);

if (!response.ok) throw new Error(`HKJData ${response.status}`);
const matches = await response.json();

足球 API 接入

重点赛事建议统一使用 priority=top。先获取 upcoming 建立本地映射，比赛开始后轮询 live，再使用 match_id 获取详情。

参数	说明	示例
`priority`	使用 top 过滤重点赛事	top
`competitions`	逗号分隔赛事 key	world-cup,premier-league
`hours`	upcoming 未来窗口，最大 168	72

股票 API 接入

股票市场使用 US、HK、CN。港股代码统一为 5 位，A 股为 6 位；搜索接口支持中文、英文、拼音和别名。

市场	代码格式	示例
US	标准 ticker；特殊代码接受别名并映射 canonical ticker	AAPL、BRK-B
HK	5 位数字	00700、09988
CN	6 位数字	600519、300750

数据质量与新鲜度

调用方不应只检查 HTTP 200，还应读取质量字段。HKJData 不会为了提高覆盖率编造数值。

updated_atHKJData 最近成功处理时间。

source_updated_at上游数据原始更新时间。

confidence_score标准化后的可信度评分。

is_stale当前数据是否已超过新鲜度阈值。

stale_reason过期原因，例如上游长时间未更新。

missing_fields当前响应缺失的字段列表。

missing_reasons每个缺失字段的具体原因。

not_applicable_fields因行业或证券类型而不适用的字段。

建议仅在接口失败、is_stale=true 或业务关键字段明确缺失时启用备用 Provider。

错误处理

错误响应始终使用 JSON。客户端应根据 HTTP 状态码和 error.code 处理，不要解析 HTML 错误页。

统一错误格式

{
  "success": false,
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Stock symbol not found",
    "details": {}
  }
}

错误码	处理建议
AUTH_REQUIRED	检查 Authorization 请求头和 API Key 状态。
SYMBOL_NOT_FOUND	先调用搜索接口确认 market 与 ticker。
DATA_SOURCE_UNAVAILABLE	短暂退避后重试，必要时使用缓存或备用源。
RATE_LIMITED	降低频率并使用指数退避。
INVALID_REQUEST	检查参数格式、市场代码和请求体。

调用频率与缓存

免费 API 保留基础防滥用、单 Key 并发和异常 IP 保护。具体额度以用户中心显示为准。

足球进行中比赛：建议 5-10 秒轮询一次。
未来赛程：建议 15-30 分钟刷新一次。
股票行情：根据市场交易时段与页面活跃度缓存。
Profile、财务和公告：优先使用 updated_at 判断是否需要重新拉取。
遇到 429 或临时 5xx：使用指数退避，不要无间隔重试。

技术支持

接入时请提供请求时间、接口路径、HTTP 状态码和错误码，不要通过邮件发送完整 API Key。

联系邮箱： [email protected]

打开完整 API Reference

足球与股票 API 接入指南

快速开始

鉴权与 API Key

推荐环境变量

第一次请求

足球 API 接入

推荐调用顺序

股票 API 接入

推荐调用顺序

数据质量与新鲜度

错误处理

调用频率与缓存

技术支持