一条curl拿到真实地址：Address开放API快速上手与Bearer Token认证完整指南

一条curl拿到真实地址：Address开放API快速上手与Bearer Token认证完整指南

【免费下载链接】addressA self-hosted address and synthetic test-profile generator for 27 countries and regions, built from real open-data streets, administrative areas, coordinates, and postcodes. Supports multilingual output, IP-nearby generation, map previews, and API access. 基于真实开放数据的自托管地址与合成测试资料生成器，覆盖 27 个国家和地区，支持多语言地址、IP 附近生成、地图预览与 API 调用项目地址: https://gitcode.com/gh_mirrors/address4/address

Address 是一个自托管的真实地址与合成测试资料生成器，数据来自官方登记和开放地图，覆盖 27 个国家和地区。通过它的开放 API，你只需一条 curl 命令加一个 Bearer Token，就能拿到带门牌、邮编和坐标的真实地址，非常适合表单测试、物流联调和地理数据演示。本文带你从零完成部署、创建令牌并发起第一次生成请求。

为什么选 Address 开放 API 拿测试地址

随机字符串拼出来的地址过不了真实校验，而 Address 返回的每一条地址都真实存在：

• 来源可追溯：地址来自官方登记、OpenStreetMap 等开放数据，附带来源与验证证据；
• 严格筛选：指定城市、区县后范围内无数据会明确报错，不会悄悄换成邻近地区；
• 配套测试资料：同一条请求还附带合成的人物、银行卡、工作等测试数据，且与真实地址无关；
• 无第三方密钥也能跑：不配置任何平台密钥即可使用开放数据源，密钥仅用于扩充数据或启用在线翻译。

第一步：用 Docker Compose 部署并确认服务就绪

生产部署只支持 docker-compose.yml 一种方式，应用、PostgreSQL、迁移与同步服务一次拉起：

git clone https://gitcode.com/gh_mirrors/address4/address cd address docker compose up -d

然后确认服务就绪（这两个端点无需令牌，是鉴权体系之外的健康检查）：

curl -fsS http://127.0.0.1:8787/api/v1/ready # => {"status":"ready"}

💡 首次同步大型国家（如美国、法国）建议 8 GB 以上内存，同步完成前不影响 API 使用。

第二步：在管理后台创建 Bearer Token

1. 浏览器打开http://127.0.0.1:8787/admin/，用初始密码admin登录后按提示修改管理员密码；
2. 进入左侧Security → API Tokens（接口令牌）；
3. 新建令牌，设置：
   • 权限范围（scope）：read（只读）或generate（可生成）；
   • 限速：每分钟请求数上限；
   • 到期时间：到期后令牌自动失效。

创建成功后会弹出一个一次性显示的令牌明文窗口，请立即复制保存——之后列表里只能看到掩码。令牌在数据库中以哈希形式存储，生成逻辑见 server/control/security.ts，编辑界面实现见 src/components/admin/security.tsx。

第三步：一条 curl 拿到真实地址

把刚才的令牌放进Authorization头，请求/api/v1/generate：

curl -fsS "http://127.0.0.1:8787/api/v1/generate?country=CN&city=深圳" \ -H "Authorization: Bearer YOUR_API_TOKEN"

响应核心结构（节选）：

{ "data": { "country": "CN", "filters": { "city": "深圳" }, "result": { "address": { "formattedAddress": "广东省深圳罗湖深南东路2671号金安大厦2栋4单元602室", "matchLevel": "premise", "propertyType": "residential", "coordinates": { "latitude": 22.54, "longitude": 114.13 } }, "profile": { "…": "合成测试资料" } } } }

几个值得留意的字段：

高频参数速查：筛选、复现与 IP 附近生成

⚠️ 筛选是严格的：所选范围内没有合格地址时返回NO_POOL_COVERAGE错误，而不会退而求其次。

批量生成与地区搜索

批量生成（一次最多 50 条，unique: true保证不重复）：

curl -fsS "http://127.0.0.1:8787/api/v1/generate/batch" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"count":20,"filters":{"country":"DE","city":"Berlin"},"options":{"unique":true}}'

地区搜索（先搜到城市，再把返回的id传给/generate）：

curl -fsS "http://127.0.0.1:8787/api/v1/locations/search?country=CN&field=city&q=南" \ -H "Authorization: Bearer YOUR_API_TOKEN"

哪些国家现在能生成？

调用GET /api/v1/countries可看到每个国家当前可生成的地址数，GET /api/v1/availability则只列出“现在就能生成”的国家。管理端有对应的数据监控页，可按国家查看同步完成度：

认证与错误处理：401、429 与错误码

错误统一为{ "error": { "code", "message" } }结构，请依据error.code写逻辑，不要解析message文本。

进阶：多语言地址与完整参数表

• 地址翻译：POST /api/v1/address-translation可将地址译为en、zh-CN、ja等 9 种语言，门牌号、邮编等数字始终保留；
• 交互式文档：服务运行后访问/zh-CN/api/页面，或直接拉取/api/v1/openapi.json导入 API 工具；
• 第三方密钥：地图与翻译平台密钥均为可选项，在管理后台“地图密钥 / 在线翻译”中添加，说明见 docs/API_KEYS.zh-CN.md。

延伸阅读

至此，你已经用一条 curl 从 Address 开放 API 拿到了可追溯来源的真实地址。接下来不妨试试seed复现、批量生成，或把/countries接到你的测试流水线里 🚀

【免费下载链接】addressA self-hosted address and synthetic test-profile generator for 27 countries and regions, built from real open-data streets, administrative areas, coordinates, and postcodes. Supports multilingual output, IP-nearby generation, map previews, and API access. 基于真实开放数据的自托管地址与合成测试资料生成器，覆盖 27 个国家和地区，支持多语言地址、IP 附近生成、地图预览与 API 调用项目地址: https://gitcode.com/gh_mirrors/address4/address