开发者 API

地址生成器 API

通过一个 JSON 接口生成逼真的虚拟地址、邮编、电话号码和合成用户资料。

格式JSON

认证无需 Key

限额600/小时

CORS已开启

接口地址

响应为 JSON，并包含 CORS 头，可用于脚本、后端服务、CI 任务和浏览器端开发工具。

GEThttps://genaddr.com/api/v1/address

快速开始

发送 GET 请求即可使用。公共接口不需要 API Key。

curl "https://genaddr.com/api/v1/address"

查询参数

countryUS

ISO-3166 alpha-2 国家/地区代码。支持：US, CA, GB, AU, DE, FR, ES, IT, NL, JP, KR, CN, TW, HK, SG, TH, PH, MY, TR, VN, IN。

admin1随机

州、省、都道府县或地区代码。别名：state、region、province。

city随机

精确城市名。支持 Los-Angeles 这样的 URL 友好写法。

count1

生成 1 到 100 条记录。多条记录会返回 addresses 数组。

has_number0

兼容需要门牌号街道地址的集成。别名：hasNumber。

请求示例

两个加州地址

curl "https://genaddr.com/api/v1/address?country=US&state=CA&count=2"

带门牌号的洛杉矶地址

curl "https://genaddr.com/api/v1/address?country=US&state=CA&city=Los-Angeles&has_number=1"

国际测试数据

curl "https://genaddr.com/api/v1/address?country=JP&admin1=40&city=Tokyo&count=3"

代码示例

可在前端工具、后端任务、自动化测试和种子脚本中调用地址生成 API。这些示例只请求合成测试数据。

JavaScript fetch

const res = await fetch("https://genaddr.com/api/v1/address?country=US&state=CA&count=5");
const data = await res.json();
console.log(data.addresses ?? [data.address]);

Python requests

import requests

res = requests.get("https://genaddr.com/api/v1/address", params={"country": "DE", "count": 3})
res.raise_for_status()
print(res.json())

OpenAPI 结构

下载机器可读的 OpenAPI 结构，用于生成客户端、API 目录、文档工具和契约测试。

查看 openapi.json

响应示例

{
  "status": "ok",
  "meta": {
    "apiVersion": "v1",
    "count": 1,
    "country": "US",
    "admin1": "CA",
    "city": "Los Angeles",
    "hasNumber": true,
    "datasetVersion": "2026-06-02"
  },
  "address": {
    "country": "US",
    "countryName": "United States",
    "fullName": "Quinn Hayes",
    "street": "9942 Willow Creek Road",
    "city": "Los Angeles",
    "admin1Code": "CA",
    "postal": "90001",
    "phone": "+1 562 907 2402",
    "email": "quinn.hayes@example.com",
    "unverifiable": {
      "street": { "unverifiable": false, "source": "openaddresses" }
    }
  }
}

响应字段

每条记录包含地址、用户资料、电话和传真、就业数据、支付测试字段、登录字段、User-Agent、地图 URL 和来源标记。

开发者使用场景

QA 自动化为 Playwright、Cypress、Selenium 和 API 集成测试生成可重复的地址记录。
数据库种子数据用合成地址、电话、邮箱、公司和资料字段填充测试或预发布数据库。
结账校验在不使用客户数据的情况下测试配送、账单、邮编和电话号码校验流程。
演示和原型为仪表盘、CRM 表格、注册流程和后台工具填充逼真的示例数据。

限流和错误

公共调用按 IP 限制为每小时 600 次。响应包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。

400 unsupported_country - 国家/地区代码不在数据集中。
404 not_found - 未找到匹配的州、地区或城市。
429 rate_limit_exceeded - 客户端超过小时限额。

负责任使用

API 返回的所有个人数据都是虚构的，仅用于开发和测试。请勿用于冒充、身份验证、支付尝试或违法用途。

常见问题