开始前
你需要一个引见商户账号、至少一批已经由桌面客户端采集并回传的数据，以及一个 API 密钥。开放 API 是已采集 GEO 数据的只读出口，不能发起新的 AI 引擎采集。
1 · 签发密钥
在引见桌面客户端的「API 密钥」页创建密钥，填写便于识别的名称并只授予需要的读取 scope。完整密钥只显示一次；立即复制到密码管理器或密钥管理服务，不要写进代码仓库、日志或前端包。
bash
export YINJEN_API_KEY="yj_live_replace_with_your_key"
2 · 第一个请求
读取引擎目录不需要任何业务参数，适合先验证网络、鉴权和响应头。成功时返回 12 个引擎的稳定 id、名称与颜色。
bash
curl https://api.zhimahang.com/v1/engines \
-H "Authorization: Bearer $YINJEN_API_KEY"
保存响应头里的 X-Request-Id。若请求失败，它是支持人员定位同一次服务端请求的唯一抓手。
3 · 第一个有意义的查询
下面查询半开时间窗 [since, until) 内的可见度时间序列。时间值是 Unix 毫秒；示例窗口为 7 天。生产集成应在每次运行时计算窗口，不要长期照抄示例时间戳。
bash
curl --get https://api.zhimahang.com/v1/metrics/visibility \
-H "Authorization: Bearer $YINJEN_API_KEY" \
--data-urlencode "since=1787558400000" \
--data-urlencode "until=1788163200000"
Python · 仅标准库
python
import json, os, time, urllib.parse, urllib.request
base = os.getenv("YINJEN_API_BASE", "https://api.zhimahang.com")
key = os.environ["YINJEN_API_KEY"]
until = int(time.time() * 1000)
since = until - 7 * 24 * 60 * 60 * 1000
query = urllib.parse.urlencode({"since": since, "until": until})
request = urllib.request.Request(
f"{base}/v1/metrics/visibility?{query}",
headers={"Authorization": f"Bearer {key}"},
)
with urllib.request.urlopen(request, timeout=30) as response:
print(json.dumps(json.load(response), ensure_ascii=False, indent=2))
Node.js 18+
javascript
const base = process.env.YINJEN_API_BASE ?? "https://api.zhimahang.com";
const key = process.env.YINJEN_API_KEY;
if (!key) throw new Error("YINJEN_API_KEY is required");
const until = Date.now();
const since = until - 7 * 24 * 60 * 60 * 1000;
const url = new URL("/v1/metrics/visibility", base);
url.search = new URLSearchParams({ since: String(since), until: String(until) });
const response = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(JSON.stringify(await response.json(), null, 2));
开放 API 只读取已经采集的数据。查不到数据时，先确认桌面客户端已完成采集与回传，再核对时间窗。
