一个请求，一条真实地址。

抽取单个地址

国家代码使用 ISO 3166-1 alpha-2。州省、城市和邮编为严格匹配；不存在的范围返回 404。中国大陆代码 CN 返回 400。

GET /api/v1/generate?country=US&region=CA

// 浏览器同源调用
const response = await fetch(
  '/api/v1/generate?country=US&region=CA'
);
if (!response.ok) throw new Error('没有匹配地址');
const { data } = await response.json();
console.log(data[0]);

可选参数：country、region、city、postcode（或 zip）、residential=true。结果包含 data 数组、matched 匹配条数和 exhausted 标记。

批量抽取

每次 1–50 条，无重复。需要登录会话或个人 API 密钥；同一账户每日批量抽取上限 5,000 条（UTC）。当数据不足时，返回全部匹配记录并将 exhausted 设为 true。

POST /api/v1/generate/batch
Authorization: Bearer YOUR_OPENADDR_KEY
Content-Type: application/json

{
  "count": 10,
  "filters": { "country": "DE", "residential": true },
  "excludeAddressIds": []
}

密钥仅显示一次，90 天过期。撤销后立即失效。请只在服务器环境中保存密钥。

可用接口

返回字段

{
  "id": "数据源的稳定记录标识",
  "country": "US",
  "region": "CA",
  "city": "Grass Valley",
  "postcode": "95945",
  "line1": "560 Penstock Drive",
  "line2": "",
  "lat": 39.213076,
  "lon": -121.077583,
  "source": "rrad",
  "sourceUrl": "https://github.com/EthanRBrown/rrad",
  "residential": false,
  "evidence": "未单独验证住宅用途"
}

缺失的文本字段为空字符串。residential 表示存在住宅用途标签，不表示政府认证。经纬度为源数据坐标，建筑记录可能使用中心点。

访问与错误

本站目前私密发布，仅站点所有者可访问。API 密钥只负责应用内批量接口认证，不会绕过站点的访问限制；外部服务器调用需在站点开放访问后使用。