API 参考

通过 ECONALK 公开 API，您可以以编程方式查询已发布的文章和经济日历事件。所有端点都需要在开发者控制台中创建的 API 密钥。

基础 URL

https://econalk.com/api/v1

身份验证

将 API 密钥作为 Bearer 令牌放在 Authorization 头中。密钥仅在创建时显示一次 — 请妥善保管。

Authorization: Bearer ek_live_<your-key>

也可以通过 X-API-Key 头传递密钥。

等级、速率限制与每月配额

限制跟随您的 ECONALK 会员身份：控制台和 API 密钥直接使用您的 ECONALK 账户，无需单独注册开发者账号。会员获得 Member 等级；ECONALK 高级会员会在一小时内（访问控制台时立即）自动升级。

等级	速率限制	每月含量	超量计费	硬上限
Member（免费）	60 req/min	10,000	$2 / 1,000 req	20,000
Premium	300 req/min	100,000	$1 / 1,000 req	500,000

每分钟限制使用固定的 60 秒窗口。每月配额统计当前 UTC 月内的所有请求；超出含量的用量按等级单价计量计费（可在开发者控制台实时查看），达到硬上限后请求将被 429 quota_exceeded 拒绝。每个响应都包含以下头部：

头部	说明
X-RateLimit-Limit	每分钟允许的最大请求数（按等级）
X-RateLimit-Remaining	当前窗口剩余请求数
X-RateLimit-Reset	窗口重置的 Unix 时间戳（秒）
Retry-After	重试前需等待的秒数（仅 429 响应）
X-Quota-Tier	解析出的等级：free 或 premium
X-Quota-Included	当前月度周期包含的请求数
X-Quota-Used	本周期已使用的请求数
X-Quota-Remaining	剩余的含量请求数（计量超额期间为 0）

响应格式

成功（列表）

{
  "data": [ /* array of objects */ ],
  "pagination": {
    "total": 142,
    "limit": 20,
    "offset": 0
  }
}

成功（单个）

{
  "data": { /* single object */ }
}

错误

{
  "error": {
    "code": "invalid_region",
    "message": "region must be us, kr, or jp"
  }
}

HTTP 状态	code	含义
400	invalid_params	查询参数值无效
401	unauthorized / invalid_key	API 密钥缺失、无效或已吊销
429	rate_limited	超过每分钟速率限制 — 参见 Retry-After
429	quota_exceeded	达到每月硬上限 — 于下个 UTC 月开始时重置
500	internal_error	意外的服务器错误

GET /api/v1/articles

返回跨地区已发布文章的分页列表。

查询参数

参数	类型	必填	默认值	说明
region	string	否	us	版本：us、kr 或 jp
category	string	否	—	按分类 slug 过滤（如 economy、tech）
q	string	否	—	标题与描述的全文搜索
from	string (YYYY-MM-DD)	否	—	包含该日期（含）之后发布的文章
to	string (YYYY-MM-DD)	否	—	包含该日期（含）之前发布的文章
sort	date_desc \| date_asc	否	date_desc	按发布日期排序
limit	integer	否	20	每页结果数（1–100）
offset	integer	否	0	分页偏移量

请求示例

curl "https://econalk.com/api/v1/articles?region=us&category=economy&limit=5" \
  -H "Authorization: Bearer ek_live_..."

响应示例

{
  "data": [
    {
      "slug": "2026-06-01-fed-rate-decision",
      "title": "Fed holds rates steady amid inflation data",
      "description": "The Federal Reserve opted to keep ...",
      "category": "economy",
      "region": "us",
      "date": "2026-06-01",
      "author": "ECONALK Editorial",
      "image": "/images/fed-rate.jpg"
    }
  ],
  "pagination": { "total": 142, "limit": 5, "offset": 0 }
}

GET /api/v1/articles/{slug}

按 slug 返回单篇文章（包含完整渲染内容）。

路径参数

参数	类型	必填	默认值	说明
slug	string	是	—	文章 slug（来自列表端点）

查询参数

参数	类型	必填	默认值	说明
region	string	否	us	版本：us、kr 或 jp

请求示例

curl "https://econalk.com/api/v1/articles/2026-06-01-fed-rate-decision?region=us" \
  -H "Authorization: Bearer ek_live_..."

{
  "data": {
    "slug": "2026-06-01-fed-rate-decision",
    "title": "Fed holds rates steady ...",
    "description": "...",
    "category": "economy",
    "region": "us",
    "date": "2026-06-01",
    "author": "ECONALK Editorial",
    "image": "/images/fed-rate.jpg",
    "content": "<!-- full MDX-rendered HTML string -->"
  }
}

GET /api/v1/economic-calendar

返回即将发生（及近期）的经济事件，如央行决议、CPI 发布和就业报告。

查询参数

参数	类型	必填	默认值	说明
region	string	否	us	版本：us、kr 或 jp
futureDays	integer	否	90	向后包含的天数（最多 365）
importance	integer (1–3)	否	—	最低重要度（3 = 高）
limit	integer	否	20	每页结果数（1–100）
offset	integer	否	0	分页偏移量

请求示例

curl "https://econalk.com/api/v1/economic-calendar?region=us&importance=3&futureDays=30" \
  -H "Authorization: Bearer ek_live_..."

响应示例

{
  "data": [
    {
      "eventName": "Fed Interest Rate Decision",
      "scheduledAt": "2026-07-30T18:00:00.000Z",
      "country": "United States",
      "category": "Central Bank",
      "importance": 3,
      "forecastValue": "4.25%",
      "previousValue": "4.25%",
      "actualValue": ""
    }
  ],
  "pagination": { "total": 12, "limit": 20, "offset": 0 }
}

分页

所有列表端点均支持 limit（默认 20，最大 100）和 offset（默认 0）。使用响应中的 pagination.total 计算页数：Math.ceil(total / limit)。

// Page 3 (zero-indexed), 10 per page
GET /api/v1/articles?limit=10&offset=20