真实地址生成器 API

每次返回一个带来源证据、坐标和国家格式的真实地址。

接口

GET/api/v1/countries国家、分组、能力、数据量与快捷入口

GET/api/v1/locations/search?country=US&field=city&regionId=1416&limit=20000按父级一次读取城市；州省与邮编分页

GET/api/v1/generate?country=US&residential=true&requestId=UUID随机生成一个地址

GET/api/v1/generate?mode=ip-region&ip=198.51.100.7按 IP 经纬度实时查询并回退热池

GET/api/v1/data-health逐国数据健康状态

生成参数

countryISO 3166-1 alpha-2 · 默认 USresidentialtrue | false · 具备住宅能力的国家默认 trueregion州、省、都道府县或地区的精确值regionId筛选城市和邮编的父级行政区 IDcity城市精确值cityId筛选邮编的城市 IDpostcode邮编精确值，空格不敏感field / q目录字段与搜索词：region、city、postcodecursor / limit州省/邮编每页 20—200 条；城市按父级最多 20,000 条seed可选的可复现随机种子requestId用于校验响应上下文的请求标识

响应示例

{
  "data": {
    "requestId": "UUID",
    "mode": "residential",
    "country": "US",
    "residential": true,
    "sourcesTried": ["address-pool-v2"],
    "result": {
      "addressFormats": {
        "native": { "postalLines": ["Avery Chen", "20 W 34th Street", "New York, NY 10001", "UNITED STATES"], "singleLine": "20 W 34th Street, New York, NY 10001, UNITED STATES" },
        "en": { "postalLines": ["..."], "singleLine": "..." },
        "zh-CN": { "postalLines": ["..."], "singleLine": "..." }
      },
      "profile": { "fullName": "Olivia Carter", "email": "oliviacarter0000@outlook.com" },
      "card": { "provider": "Stripe", "number": "4242 4242 4242 4242", "sandboxOnly": true },
      "googleMaps": { "status": "map_query", "embedUrl": "https://www.google.com/maps?q=LAT,LNG&z=17&output=embed" }
    }
  }
}

数据源规则

普通地址和真实住宅地址只读取服务器定期同步的 SQLite 地址池，运行时不调用在线 Provider、翻译或地理编码。只有显式 IP 区域模式查询实时源；失败后按附近、城市、州省、国家地址池回退。住宅模式始终要求独立住宅用途证据。