AddressQA Edge REST API 参考文档

部署于 Cloudflare Pages Functions 的无状态、确定性测试数据与校验接口。支持 CORS 跨域直连,并提供标准 OpenAPI 3.1.0 JSON 规范文件下载。

Download /openapi.json 打开交互控制台
Endpoint 01 · Deterministic Fixtures

GET /api/v1/fixtures

GET /api/v1/fixtures 查询参数规范
参数名 默认值 合法取值与说明
country US 24 国 ISO 码或路径别名(US、GB/UK、JP、CA、DE、FR、AU、TW、SG、HK、KR 等)
state ALL 州/省代码(如 DE、OR、NH、MT、AK、CA、NY、ON)或 ALL
taxFree false true 时仅在 US 5 大免税州(DE、OR、NH、MT、AK)中抽取
phoneMode safe safe | mobile | landline | tollfree
boundary normal normal | leading_zero | long_street | unicode | punctuation_name | unit_suite
count 1 生成记录条数(1..50)
seed qa-checkout-01 任意字符串种子,保证跨环境逐字节一致
format json json | stripe | playwright | sql | csv
# 1. Fetch 3 deterministic New Hampshire leading-zero tax-free fixtures as JSON
curl -sS "https://addressqa.com/api/v1/fixtures?country=US&state=NH&boundary=leading_zero&count=3&seed=qa-nh-01" | jq .

# 2. Fetch ready-to-use Stripe Checkout payload for Delaware
curl -sS "https://addressqa.com/api/v1/fixtures?country=US&state=DE&seed=qa-stripe-de&format=stripe"

# 3. Export Excel-safe RFC 4180 CSV
curl -sS "https://addressqa.com/api/v1/fixtures?country=US&taxFree=true&count=10&format=csv" -o taxfree.csv
Endpoint 02 · Format Diagnostics

GET / POST /api/v1/validate

# GET query validation
curl -sS "https://addressqa.com/api/v1/validate?country=JP&postal=%E3%80%92%EF%BC%91%EF%BC%95%EF%BC%90%EF%BC%8D%EF%BC%90%EF%BC%90%EF%BC%90%EF%BC%91&phone=090-0000-4120" | jq .

# POST JSON validation
curl -sS -X POST "https://addressqa.com/api/v1/validate" \
  -H "Content-Type: application/json" \
  -d '{"country":"GB","postal":"SW1A 1AA","phone":"07700 900123"}' | jq .
FAQ

API 使用常见问题

调用 /api/v1/fixtures 需要 API Key 吗?
不需要。公开测试夹具与校验接口均开启 CORS 并直接运行在 Cloudflare Pages Functions 全球边缘节点,可直接接入 Playwright、GitHub Actions 或 Postman。
如何保证不同时间拉取的 API 响应完全一致?
显式传入 seed 参数(例如 seed=qa-checkout-01)以及确定的 country、state、boundary 与 count,边缘节点会基于 Mulberry32 返回完全一致的响应体。