开源的「真实地址 + 合成测试资料」生成器(27 国)

4天前更新 2,440 0 0

Address 是一个基于真实开放数据自托管的测试资料生成器:覆盖 27 个国家和地区,返回带来源、精度与坐标的真实街道地址,面向开发测试、表单与物流演示,代码 MIT 开源,可自托管或用公开演示站。

收录时间:
2026-07-28
其他站点:

开源的「真实地址 + 合成测试资料」生成器(27 国)

图:Address 生成器主页,可按国家地区与当前 IP 区域生成真实街道地址(2026-11 截图)

定位与基本信息

Address 是一个开源的测试资料生成器,仓库在 GitHub 的 daimon3332/address,MIT 许可证,配套公开演示站即本站链接的 address.333186.xyz。它解决的是开发测试中的一个具体麻烦:填表单、测结账流程、验证地址格式时,需要「看起来真实、结构也真实」的地址,而随手编的街道和邮编往往对不上行政区划。它的做法不是随机拼字,而是从官方地址登记、开放地图数据里取真实存在的街道与门牌记录,生成带来源标注、精度标注和经纬度坐标的地址条目。覆盖 27 个国家和地区,支持 10 种显示语言,可在线用演示站,也可整套自托管部署。截至 2026 年 11 月快照,仓库约 2,297 个星标、338 个 fork,2026 年 7 月创建,11 月当日仍有代码推送,是活跃维护中的项目。

平台背景

这是一个个人开源项目,技术栈写得很明白:前端 Astro 加 React,接口用 Hono,数据库 PostgreSQL 16,运行时 Node.js 24,靠一个同步服务持续从官方登记库、OpenStreetMap、Overture 等开放数据源增量导入。作者在文档里立了个规矩:地址库的每条记录必须能溯源,缺失的字段宁可留空也不编造——这也是它区别于网上那些「随机地址生成器」的根本点,后者多是把街道名、门牌号、邮编随机组合,生成根本不存在的地址。它明确把用途定位在开发测试:表单与结账测试、地址格式验证、物流演示。演示站页面底部也标注了数据版权:地址数据来自 OpenStreetMap 贡献者及所列公开来源,遵循 ODbL 许可。

开源的「真实地址 + 合成测试资料」生成器(27 国)

图:演示站的地址数量监控页,公开各国家地区的覆盖数据(2026-11 截图)

核心服务与功能

  • 27 国地址生成:北美(美国、加拿大、墨西哥)、欧洲(英国、德国、法国、意大利、西班牙、荷兰、俄罗斯)、东亚(中国、香港、台湾、日本、韩国)、东南亚(新加坡、马来西亚、泰国、菲律宾、越南)、南亚(印度)、大洋洲(澳大利亚)、中东(土耳其、沙特)、南美(巴西)、非洲(尼日利亚、南非)。
  • 按真实行政层级筛选:可按国家、城市、区县、邮编逐级过滤,层级跟随各国真实行政区划;某个筛选条件下没有数据时直接返回错误,而不是悄悄换个地区糊弄。
  • 精度与来源标注:每条结果标注精度等级(街道级、门牌级、单元级)和物业类型,中国地址以住宅小区为主,其他国家多为门牌与街道级记录,有独立居住证据时才标为住宅。
  • IP 附近生成:演示站可按访问者当前 IP 所在区域就近生成地址,测试地域相关功能时很顺手。
  • 多语言与地图预览:结果可按本地语言、英文、简繁中文、日语、韩语、德语、法语、西班牙语、葡萄牙语显示,并可一键在 Google 地图或高德地图打开核对位置。
  • 覆盖监控:演示站公开了各国地址数量监控页,数据家底摆在明面上。
  • 开放 API:自托管实例提供 Bearer 令牌鉴权的 JSON API,支持单条与批量生成、地点搜索、覆盖查询和地址翻译,附 OpenAPI 3.1 文档。

生成结果的字段结构以仓库给出的 API 示例为准:包含格式化后的完整地址字符串、精度等级(matchLevel,分为街道、门牌、单元三档)、物业类型(有独立居住证据时才标 residential)和经纬度坐标;筛选条件没命中时会明确标注匹配层级,而不是默默放宽。自托管实例还带一个功能完整的管理后台:数据看板、各国工作区、同步历史、快捷地点、服务商密钥、翻译路由、访问控制和 API 令牌都在里面,演示站的监控页就是这个后台公开出来的一部分。

使用方式

轻量用法是直接打开演示站:选国家(或点按 IP 区域生成),需要时再细选州省、城市,点生成即可,结果能复制、导出或收藏;页面还贴心地列了美国无州销售税的五个州和热门城市的快捷入口,这正是电商结账测试的高频需求。正式用法是自托管:服务器需 Linux、Docker 24 以上和 Docker Compose v2,内存 4GB 起步(首次导入大国数据建议 8GB),拉取仓库的 docker-compose.yml 一条命令启动,应用、数据库、迁移和同步服务会一起拉起,初始管理员密码登录后必须修改,之后在管理后台决定公开生成页是否也要密码、并签发 API 令牌。系统默认只监听本机 8787 端口,对外提供服务需自己加 HTTPS 反向代理。

它的同步机制决定了数据的「新鲜度口径」:同步服务对每个数据源做增量导入,失败有次数上限的重试和指数退避,配额耗尽会等待,某个数据源被证实没有新数据后,该国会标记为「来源已达上限」并停止反复入队。一个国家在库里算「完整」,要同时满足三个条件:有效地址总量达标、最低层级行政区覆盖达标、每一级节点数量达标。这些规则都写在仓库文档里,选型时可以据此判断它和「抓一把随机数据塞进数据库」的同类小工具不是一回事。

适用人群

适合跨境电商、独立站开发者测试结账与税务逻辑(不同州省的地址格式与税区差异最容易在测试阶段漏掉),适合做表单与地址校验的程序员,适合物流、地图类产品的演示与联调,也适合本地化团队核对各国地址书写格式。不适合的场景同样明确:它不是「虚拟身份」工具,生成资料的正当用途到测试为止,下一节会专门说明边界。

开源的「真实地址 + 合成测试资料」生成器(27 国)

图:演示站的 API 文档页(2026-11 截图)

免费与付费对照

项目 说明
代码 MIT 开源,免费自托管;官方 Docker 镜像公开提供
公开演示站 免费使用,未见收费说明;长期可用性以站方为准
自托管成本 自己的服务器费用;基础数据源免授权使用,部分国家数据与在线翻译可选用自备的地图/翻译服务密钥增强
数据许可 上游数据集保留各自许可,OpenStreetMap 数据须按 ODbL 署名要求使用

优缺点

优点

  • 数据真实可溯源:地址来自官方登记与开放数据,带精度和坐标,不是随机拼凑,拿去测结账和物流不容易被格式校验打回来。
  • 筛选诚实:没数据就报错,不偷偷换地区,这对测试数据的可信度是关键品质。
  • 自托管门槛低:一个 Compose 文件拉起全套,密钥自动生成持久化,文档里部署、升级、备份恢复都写全了。
  • 维护活跃:2026 年 7 月发布后持续更新,抓取当日仍有推送(2026-11 快照)。

缺点

  • 覆盖不均:27 国的数据深度差别很大,小国可能只有主要城市,自托管首次导入大国数据也吃内存和时间。
  • 演示站是个人项目,稳定性和速率没有承诺,正式业务联调建议自托管。
  • 中国地址以小区级为主、其他国家精度口径不一,拿结果做统计或训练数据前要先理解各国的精度标注。
  • 「真实地址」是双刃剑:记录对应真实存在的街道门牌,使用边界必须守住,见下一节。

同类竞品对比

维度 Address Free Public APIs Cloudflare AI Web
定位 专门的测试地址生成器 免费公共 API 目录 AI 网页与接口工具集合
数据方式 真实开放数据加自托管同步 收录第三方现成接口 在线工具即开即用
可自托管 支持,Docker 一键部署 不适用(目录站) 不支持
适合 需要成体系测试数据的开发团队 找练手 API 的开发者 零散的网页端小需求

Free Public APIs 里也能找到随机用户、地址类的练习接口,但那类接口的数据多为虚构拼凑且服务稳定性看第三方脸色;Address 的差异在于数据真实性和可自托管,代价是要自己运维一套服务。

注意事项与风险

  • 用途边界(重要):本站与原项目都把定位写得很清楚——这是开发测试工具。生成结果是合成测试资料,只能用于表单测试、结账联调、格式验证、物流演示等开发场景,不得用于实名注册、冒充他人身份、绕过平台风控、欺诈交易等违法违规用途,这类行为与使用者自行承担全部法律责任。
  • 地址记录对应真实地理位置,可能涉及真实住户:禁止用于邮寄骚扰、线下滋扰或任何形式的精准投送。
  • 拿生成资料注册的测试账号不要混入生产环境;测试数据与真实用户数据混杂会给后续合规审计埋雷。
  • 自托管时务必修改默认管理员密码并给公开生成页设置访问控制,避免自己的实例被他人滥用为批量生成入口。
  • 商用引用其数据时保留上游署名:OpenStreetMap 等数据源遵循 ODbL 等许可,署名义务不因工具开源而免除。

数据统计

相关导航

暂无评论

none
暂无评论...