v1.0 免费开放 无需 API Key 无需登录 85 国 · 4 语言

Global Address Generator API

一行代码批量生成可复现的假身份数据，用于数据库测试、UI 原型、自动化用例。支持 JSON / CSV / XML / YAML / vCard / SQL、Seed 种子复现、浏览器跨域调用。

🆓
免费公开测试阶段：当前 API 完全免费、无需 API Key、无需登录，直接向所有开发者开放。付费计量层（API Key / 套餐 / 仪表盘）将在产品成熟、用户量增长后再上线，不影响你现在的调用。限速为每 IP 30 次/分钟，超出返回 429。

Base URL

GET https://globaladdressgenerator.com/api/generate

所有请求均为 GET，参数通过 query string 传递。无需 API Key，无需登录。

快速开始

curl "https://globaladdressgenerator.com/api/generate?country=us&lang=zh&count=5&seed=demo"

返回 5 个美国身份（中文本地化字段），使用固定种子 demo —— 任何人任何时候用同一链接都会得到完全相同的结果。

请求参数

参数类型默认值说明
countrystring随机 ISO 风格国家代码：us jp kr gb de fr cn ca au br in it es mx ru kz 等共 85 国。省略则随机。
langstringen 本地化字段语言：zh / en / ja / ko。
countinteger1 生成数量，范围 1–100。
seedstring随机 种子字符串。相同种子 → 完全相同结果，用于可复现测试。
formatstringjson 返回格式：json、csv、html、xml、yaml、vcard、sql、mysql、postgresql、sqlite、oracle、mssql、xlsx、psv。
fieldsstring全部 逗号分隔的字段路径，仅返回指定字段。支持点号嵌套，如 firstName,lastName,email,address.city,address.zipCode。
incstring全部 randomuser 风格：逗号分隔的顶层字段白名单，如 name,email,phone。支持 randomuser 别名：name→姓名、location→地址、login、dob、picture、registered、id、cell、nat。与 fields 可叠加使用。
excstring无 randomuser 风格：逗号分隔的顶层字段黑名单，如 ssn,password。同样支持 randomuser 别名（name/location/login/dob/picture/id 等）。
noinfoboolean0 设为 1 时，JSON/JSONP 响应中省略 info 元数据，仅返回 results。
natstring随机 randomuser 风格的国家别名，效果等同于 country，如 nat=us。
callbackstring无 JSONP 回调函数名，如 callback=myFunc。仅对 format=json 生效，返回 myFunc({...})。
⚠️
速率限制：每个 IP 30 次 / 分钟。超出返回 429 Too Many Requests。批量需求请使用 count 参数而非循环请求。每次响应都带配额头：X-RateLimit-Limit（30）、X-RateLimit-Remaining（剩余次数）、X-RateLimit-Reset（窗口重置的 Unix 时间戳）。
🌐
跨域（CORS）：已开放，任何网站的前端（浏览器 fetch）均可直接调用，无需后端代理。响应头 Access-Control-Allow-Origin 反射调用方域名。

响应格式

JSON 响应包含 results 数组与 info 元数据：

{
  "results": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "gender": "Male",
      "age": 34,
      "email": "[email protected]",
      "phone": "+1-415-555-0142",
      "address": {
        "street": "123 Oak Avenue",
        "city": "New York",
        "state": "NY",
        "zipCode": "10001",
        "country": "United States",
        "countryCode": "us"
      },
      "avatar": "data:image/svg+xml;base64,...",
      "seed": "a1b2c3d4"
    }
  ],
  "info": { "version": "1.0", "seed": "a1b2c3d4", "count": 1, "country": "us", "lang": "en" }
}

每个身份含 80+ 字段（姓名、地址、联系、工作、身体特征、社交等）。使用 fields 参数可精简返回。

发现端点：GET /api/countries

GET https://globaladdressgenerator.com/api/countries

枚举支持的国家码与语言，便于第三方接入时自查参数。不限流、可缓存（Cache-Control: public, max-age=86400）。

{
  "version": "1.0",
  "total": 85,
  "languages": ["zh", "en", "ja", "ko"],
  "countries": [
    { "id": "us", "name": "美国", "flag": "🇺🇸" },
    { "id": "jp", "name": "日本", "flag": "🇯🇵" },
    { "id": "gb", "name": "英国", "flag": "🇬🇧" }
  ]
}

健康检查：GET /api/version

GET https://globaladdressgenerator.com/api/version

返回当前 API 版本与覆盖规模，供 uptime 监控与文档引用。无需鉴权、不限流。

{
  "version": "1.0",
  "engine": "src/engine",
  "countries": 85,
  "languages": 4,
  "status": "ok"
}

代码示例

# 生成 5 个美国身份（中文），固定种子可复现
curl "https://globaladdressgenerator.com/api/generate?country=us&lang=zh&count=5&seed=demo"

# 仅返回姓名与邮箱（字段过滤）
curl "https://globaladdressgenerator.com/api/generate?fields=firstName,lastName,email"

# CSV 格式导出
curl "https://globaladdressgenerator.com/api/generate?count=10&format=csv"

# XML / YAML / vCard / SQL 格式
curl "https://globaladdressgenerator.com/api/generate?count=5&format=xml"
curl "https://globaladdressgenerator.com/api/generate?count=5&format=yaml"
curl "https://globaladdressgenerator.com/api/generate?count=2&format=vcard"
curl "https://globaladdressgenerator.com/api/generate?count=5&format=sql"

# randomuser 风格字段过滤 + JSONP
curl "https://globaladdressgenerator.com/api/generate?inc=name,email,phone&noinfo=1&callback=handleData"
// 浏览器 / Node.js 均可直接调用（已开放 CORS）
const res = await fetch(
  'https://globaladdressgenerator.com/api/generate' +
  '?country=us&count=3&seed=demo&lang=zh'
);
const data = await res.json();

for (const p of data.results) {
  console.log(p.firstName, p.lastName, p.email, p.seed);
}

// 字段过滤：只要姓名 + 城市
const r2 = await fetch(
  'https://globaladdressgenerator.com/api/generate' +
  '?fields=firstName,lastName,address.city'
);
console.log(await r2.json());
import requests

# 生成 10 个英国身份，英文，固定种子
r = requests.get('https://globaladdressgenerator.com/api/generate',
                 params={'country': 'gb', 'count': 10,
                         'seed': 'demo', 'lang': 'en'})
profiles = r.json()['results']

for p in profiles:
    print(p['firstName'], p['lastName'], p['email'])

# 字段过滤 + CSV 导出
r2 = requests.get('https://globaladdressgenerator.com/api/generate',
                  params={'count': 50, 'format': 'csv',
                          'fields': 'firstName,lastName,address.city'})
with open('fake_users.csv', 'w', encoding='utf-8') as f:
    f.write(r2.text)

在线试用

直接在浏览器里调用真实 API（本页部署后指向生产环境，开发/预览环境指向本地）。可选接口、国家、语言实时测试，结果区显示状态码、CORS 与限流头，并支持一键复制。

就绪。点击「发送请求」调用真实接口。
// 点击「发送请求」查看实时返回

典型用途

数据库测试

批量灌入 1000+ 假身份，测试分页、索引、查询性能。

UI 原型设计

填充用户列表、个人资料页 mockup，含头像与本地化字段。

自动化测试

固定 seed 让每次 CI 拿到相同数据，bug 可精确复现。

教学演示

课堂上快速生成示例数据，演示 API 调用与数据处理。

错误码

状态码含义原因
200成功正常返回数据。
400参数错误country 代码无效（invalid_country），或 count/format 非法（bad_request，极少触发，已自动夹紧）。
405方法不允许使用了非 GET 方法。
429请求过于频繁超过 30 次/分钟/IP 限流。响应体含 retry_after（秒），并带 X-RateLimit-* 头。
500服务器错误生成过程异常（generation_failed）。
503服务暂不可用API 开关关闭（api_disabled），仅作安全兜底，正常运营时不出现。
💡
想要更多字段（车辆、宗教、比特币地址、追踪号码等）？已在 v1.1 路线图中。欢迎通过 联系我们 反馈需求。

← 返回首页生成器