如何让生成的地址靠近用户所在地点：Address IP定位生成模式实战指南
【免费下载链接】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 地址生成器支持 IP 定位生成模式（mode=ip-region）：它自动识别调用方的 IP 位置，从真实开放数据街道中生成靠近用户所在城市的地址，覆盖 27 个国家与地区，并附赠合成测试资料，非常适合做本地化测试与模拟下单场景。
IP定位生成模式是什么？
普通生成模式下，你需要手动指定country、city等参数；而IP 定位生成模式只认一件事：调用者在哪，地址就在哪。
它的工作链路非常直观：
- 识别 IP—— 服务器读取请求来源 IP（反向代理下读取
X-Forwarded-For等转发头）； - 解析位置—— 调用 IP 地理定位服务，得到国家、州/省、城市、邮编与经纬度；
- 就近选取—— 优先按坐标找数据库中最近的已发布地址，找不到则回退到城市级匹配；
- 返回结果—— 响应中带
ipMatchLevel（coordinate / city）与distanceKm（距离 IP 的公里数），让你清楚知道地址有多"近"。
💡 IP 模式下只要求匹配到城市及以上精度。如果该城市没有同步过地址数据，API 会直接返回
IP_REGION_NO_RESULT，而不是悄悄给你一个"全国随便挑"的地址——这种"宁缺毋滥"对测试的可信度非常重要。
三种调用方式：一键上手
所有请求都需要在管理后台API Tokens页面创建令牌，并带上Authorization: Bearer YOUR_API_TOKEN请求头。
方式一：不传 IP，自动使用调用方 IP（最省事）
浏览器或后端直接请求，服务器自己定位：
curl -fsS "https://address.example.com/api/v1/generate?mode=ip-region" \ -H "Authorization: Bearer YOUR_API_TOKEN"方式二：手动指定目标 IP（适合测试任意城市）
通过ip参数模拟其他位置，无需真的换网络：
curl -fsS "https://address.example.com/api/v1/generate?mode=ip-region&ip=8.8.8.8" \ -H "Authorization: Bearer YOUR_API_TOKEN"方式三：先查 IP 位置，再生成
GET /client-context可先确认某个 IP 被解析到了哪里（国家、区域、城市、邮编、坐标），再生成前做好预期：
curl -fsS "https://address.example.com/api/v1/client-context?ip=8.8.8.8" \ -H "Authorization: Bearer YOUR_API_TOKEN"三种方式对应的源码分别在 server/api/index.ts（client-context 端点）与 server/api/index.ts（ip-region 模式入口），IP 数据库的解析与双服务商容错逻辑在 server/api/services/ip-geolocation.ts。
响应字段解读：一眼看懂匹配质量
ip-region模式响应中值得关注这几个字段：
| 字段 | 含义 |
|---|---|
mode | 固定为ip-region |
ipMatchLevel | coordinate（坐标级就近）或city（城市级） |
ipRegion.distanceKm | 选中地址与 IP 坐标的距离（公里） |
ipRegion.targetRegion/targetCity | 实际落点的州/省与城市 |
address.formattedAddress | 完整地址，含真实坐标 |
如果返回 400 且error.code为IP_LOCATION_UNAVAILABLE，说明该 IP 无法解析到受支持的国家；返回IP_REGION_NO_RESULT则表示该城市还没有同步过地址池，稍后重试或换城市即可。错误码全表见 docs/API.zh-CN.md。
反向代理部署必做：让 Address 看到真实客户端 IP
生产环境通常架在 Nginx / Caddy 等反向代理之后，此时服务器只能看到代理自身的 IP。要让 IP 定位生效，需要在部署配置中设置TRUST_PROXY=true，服务器才会信任Forwarded、X-Forwarded-For、X-Real-Ip请求头中的客户端地址，相关判断逻辑见 server/api/services/client-context.ts。
⚠️ 只在确定上游代理可信时才开启该选项，否则客户端可伪造 IP 头来"指定"自己的位置。
常见问题速查
Q：为什么同一个 IP 有时是 coordinate 匹配，有时是 city 匹配？IP 数据库不一定总能给出经纬度。有坐标时走"最近地址"检索（见 server/api/repositories/address-pool-v2.ts），无坐标时按 IP 解析出的城市精确匹配，二者都是可信结果。
Q：ip-region 模式能和city、postcode参数一起用吗？不能。IP 模式下位置参数被刻意忽略，避免"IP 在 A 城、参数指定 B 城"的矛盾请求，位置只由 IP 决定。
Q：如何复现某次生成的结果？加seed参数。同一个 seed 在同一数据版本下会选中同一条记录与同一份合成资料，方便回归测试与问题排查。
Q：数据从哪里来？所有地址来自真实开放数据街道（OpenAddresses、各国官方地理数据源等）经同步管道入库，字段与证据链说明见 docs/data-sources.md；部署与运行方式见 docs/DEPLOYMENT.zh-CN.md。
小结
Address 的 IP 定位生成模式把"生成地址"和"用户位置"绑在了一起：三个参数级别的配置，就能得到带坐标、带距离、可复现的本地化测试地址。配合批量接口（POST /generate/batch）与多语言地址翻译，一套即可支撑完整的地址测试流水线。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
