真實住宅地址產生器 API

驗證

除健康檢查、就緒檢查和 OpenAPI 外，所有端點都需要管理員控制台建立的 Bearer Token。權杖支援讀取或產生權限、每分鐘限制和到期時間。

Authorization: Bearer YOUR_API_TOKEN

GET/api/v1/health

權限: public

檢查 API 程序是否可用。

參數

此端點沒有請求參數。

呼叫範例

curl "https://address.example/api/v1/health" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/health",
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/health");
const payload = await response.json();
console.log(payload);

成功回應

{
  "status": "ok"
}

GET/api/v1/ready

權限: public

檢查 API 和 PostgreSQL 是否可以接收流量。

參數

此端點沒有請求參數。

呼叫範例

curl "https://address.example/api/v1/ready" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/ready",
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/ready");
const payload = await response.json();
console.log(payload);

成功回應

{
  "status": "ready"
}

GET/api/v1/countries

權限: read

列出支援的國家、能力、地址數量和快捷區域。

參數

此端點沒有請求參數。

呼叫範例

curl "https://address.example/api/v1/countries" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/countries",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/countries", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": [
    {
      "code": "US",
      "residentialAvailable": true,
      "residentialCount": 50000,
      "generationMode": "synchronized-pool"
    }
  ]
}

GET/api/v1/availability

權限: read

傳回輕量級住宅地址可用性清單。

參數

此端點沒有請求參數。

呼叫範例

curl "https://address.example/api/v1/availability" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/availability",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/availability", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": [
    {
      "code": "US",
      "residentialAvailable": true
    }
  ]
}

GET/api/v1/client-context

權限: read

解析請求 IP 對應的國家和位置內容。

參數

ip選填 · query · string可选 IPv4 或 IPv6；省略时使用当前请求 IP。

呼叫範例

curl "https://address.example/api/v1/client-context?ip=198.51.100.7" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/client-context?ip=198.51.100.7",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/client-context?ip=198.51.100.7", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": {
    "country": "US",
    "region": "California",
    "city": "Los Angeles",
    "matchLevel": "city"
  }
}

GET/api/v1/locations/search

權限: read

分頁搜尋州省、城市、區縣或郵遞區號。

參數

country選填 · query · string · 預設值: USISO 3166-1 alpha-2 国家或地区代码。

field選填 · query · string · 預設值: city要返回的目录字段。

q選填 · query · string可选、不区分大小写的搜索文本。

region選填 · query · string精确的上级行政区值。

regionId選填 · query · string稳定的上级行政区 ID。

cityId選填 · query · string稳定的上级城市 ID。

residential選填 · query · boolean · 預設值: false仅统计已发布的住宅记录。

cursor選填 · query · string上一页返回的不透明游标。

limit選填 · query · integer · 預設值: 100 · 20-200每页 20 至 200 条。

呼叫範例

curl "https://address.example/api/v1/locations/search?country=US&field=city&regionId=1416&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/locations/search?country=US&field=city&regionId=1416&limit=100",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/locations/search?country=US&field=city&regionId=1416&limit=100", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": {
    "cities": [
      {
        "id": "example-city",
        "value": "Los Angeles",
        "availableCount": 120
      }
    ],
    "total": 1,
    "nextCursor": null
  }
}

GET/api/v1/generate

權限: generate

隨機產生一個已發布的真實住宅地址和測試資料。

參數

country選填 · query · string · 預設值: USISO 3166-1 alpha-2 国家或地区代码。

region選填 · query · string精确的一级行政区值。

regionId選填 · query · string位置搜索返回的行政区 ID。

city選填 · query · string精确城市值。

cityId選填 · query · string位置搜索返回的城市 ID。

district選填 · query · string支持国家的精确区县值。

districtId選填 · query · string位置搜索返回的稳定区县 ID。

postcode選填 · query · string精确邮编值。

postcodeId選填 · query · string位置搜索返回的邮编 ID。

mode選填 · query · string使用 ip-region 按请求或指定 IP 匹配。

ip選填 · query · stringip-region 模式使用的 IPv4 或 IPv6。

q選填 · query · string必须出现在所选地址字段中的文本。

strategy選填 · query · string · 預設值: random选择策略；两种模式都从已同步数据库选择。

residential選填 · query · boolean · 預設值: true兼容旧客户端的参数；生成接口始终返回住宅记录。

seed選填 · query · string可选的可复现随机种子。

requestId選填 · query · string调用方提供的请求关联 ID。

呼叫範例

curl "https://address.example/api/v1/generate?country=US&region=California&requestId=YOUR_REQUEST_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/generate?country=US&region=California&requestId=YOUR_REQUEST_ID",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/generate?country=US&region=California&requestId=YOUR_REQUEST_ID", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": {
    "requestId": "YOUR_REQUEST_ID",
    "country": "US",
    "mode": "residential",
    "sourcesTried": [
      "address-pool-v2"
    ],
    "result": {
      "address": {
        "id": "address-id",
        "countryCode": "US",
        "formattedAddress": "Example address"
      }
    }
  }
}

POST/api/v1/generate/batch

權限: generate

使用結構化篩選、排除條件和唯一性控制批量產生最多 50 個住宅地址。

參數

count必填 · body · integer · 1-50要生成的地址数量。

filters必填 · body · object国家以及精确行政区、邮编或文本筛选条件。

options選填 · body · object随机性、唯一性、策略和请求关联选项。

excludeAddressIds選填 · body · array不得返回的地址 ID 列表。

呼叫範例

curl -X POST "https://address.example/api/v1/generate/batch" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "count": 3,
  "filters": {
    "country": "US",
    "region": "California",
    "city": "Los Angeles"
  },
  "options": {
    "unique": true,
    "strategy": "random",
    "seed": "example-seed"
  },
  "excludeAddressIds": []
}'

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/generate/batch",
    headers={"Authorization":"Bearer YOUR_API_TOKEN","Content-Type":"application/json"},
    data=json.dumps({"count":3,"filters":{"country":"US","region":"California","city":"Los Angeles"},"options":{"unique":true,"strategy":"random","seed":"example-seed"},"excludeAddressIds":[]}),
    method="POST"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/generate/batch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "count": 3,
    "filters": {
      "country": "US",
      "region": "California",
      "city": "Los Angeles"
    },
    "options": {
      "unique": true,
      "strategy": "random",
      "seed": "example-seed"
    },
    "excludeAddressIds": []
  })
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": {
    "requestId": "batch-request-id",
    "requestedCount": 3,
    "returnedCount": 3,
    "unique": true,
    "results": [
      {
        "address": {
          "id": "address-id",
          "countryCode": "US"
        }
      }
    ]
  }
}

GET/api/v1/locations/hierarchy

權限: read

列出國家、省州或城市的下一級行政區或郵遞區號。

參數

country必填 · query · stringISO 3166-1 alpha-2 国家或地区代码。

childType必填 · query · string要返回的下级目录类型。

parentType選填 · query · string · 預設值: countryparentId 指定的上级类型。

parentId選填 · query · string稳定的省州或城市 ID；国家上级时省略。

q選填 · query · string可选的下级名称搜索文本。

residential選填 · query · boolean · 預設值: true包含住宅可用数量并禁用无覆盖选项。

cursor選填 · query · string上一页返回的不透明游标。

limit選填 · query · integer · 預設值: 100 · 20-200每页 20 至 200 条。

呼叫範例

curl "https://address.example/api/v1/locations/hierarchy?country=US&parentType=region&parentId=1416&childType=city&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/locations/hierarchy?country=US&parentType=region&parentId=1416&childType=city&limit=100",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/locations/hierarchy?country=US&parentType=region&parentId=1416&childType=city&limit=100", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": {
    "parent": {
      "type": "region",
      "id": "1416"
    },
    "childType": "city",
    "children": [
      {
        "id": "example-city",
        "value": "Los Angeles",
        "availableCount": 120
      }
    ],
    "total": 1,
    "nextCursor": null
  }
}

GET/api/v1/coverage

權限: read

傳回已啟用國家的三項同步完成規則。

參數

country選填 · query · string可选的 ISO 国家代码筛选。

includeComplete選填 · query · boolean · 預設值: true是否包含已经满足全部三项规则的国家。

呼叫範例

curl "https://address.example/api/v1/coverage?country=US&includeComplete=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/coverage?country=US&includeComplete=true",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/coverage?country=US&includeComplete=true", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": {
    "countries": [
      {
        "countryCode": "US",
        "complete": false,
        "rules": {
          "total": {
            "current": 42000,
            "target": 50000,
            "met": false
          },
          "administrativeCoverage": {
            "actual": 0.98,
            "target": 1,
            "met": false
          },
          "regionalMinimums": {
            "actual": 0.95,
            "target": 1,
            "met": false
          }
        }
      }
    ]
  }
}

GET/api/v1/addresses/{id}

權限: read

透過產生結果中的 ID 查詢目前仍在發布的同步地址。

參數

id必填 · path · string生成或批量生成接口返回的地址 ID。

呼叫範例

curl "https://address.example/api/v1/addresses/pool-v2-address-id" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/addresses/pool-v2-address-id",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/addresses/pool-v2-address-id", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": {
    "address": {
      "id": "pool-v2-address-id",
      "countryCode": "US",
      "formattedAddress": "Example address"
    }
  }
}

POST/api/v1/address-translation

權限: generate

將已同步地址翻譯為支援的顯示語言。

參數

addressId必填 · body · stringgenerate 返回的地址 ID。

targetLocale必填 · body · string目标显示语言。

呼叫範例

curl -X POST "https://address.example/api/v1/address-translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "addressId": "address-id",
  "targetLocale": "zh-CN"
}'

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/address-translation",
    headers={"Authorization":"Bearer YOUR_API_TOKEN","Content-Type":"application/json"},
    data=json.dumps({"addressId":"address-id","targetLocale":"zh-CN"}),
    method="POST"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/address-translation", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "addressId": "address-id",
    "targetLocale": "zh-CN"
  })
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": {
    "components": {
      "street": "示例街道",
      "houseNumber": "20"
    },
    "lines": [
      "示例地址"
    ],
    "singleLine": "示例地址"
  }
}

GET/api/v1/data-health

權限: read

報告各國同步地址池健康狀態和設定錯誤。

參數

此端點沒有請求參數。

呼叫範例

curl "https://address.example/api/v1/data-health" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \

import json
from urllib.request import Request, urlopen

request = Request(
    "https://address.example/api/v1/data-health",
    headers={"Authorization":"Bearer YOUR_API_TOKEN"},
    method="GET"
)
with urlopen(request) as response:
    print(json.load(response))

const response = await fetch("https://address.example/api/v1/data-health", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN"
  },
});
const payload = await response.json();
console.log(payload);

成功回應

{
  "data": {
    "healthy": true,
    "countries": [
      {
        "code": "US",
        "ready": true,
        "count": 50000
      }
    ],
    "configurationErrors": []
  }
}

錯誤處理

400INVALID_REQUEST

401UNAUTHORIZED

404NO_POOL_COVERAGE / ADDRESS_NOT_FOUND

429RATE_LIMITED · Retry-After: 60

500 / 503INTERNAL_ERROR / SERVICE_UNAVAILABLE