開發者 API

地址產生器 API

透過單一 JSON 端點產生逼真的虛擬地址、郵遞區號、電話號碼與合成使用者資料。

格式JSON

認證無需 Key

限制600/小時

CORS已啟用

端點

回應為 JSON，並包含 CORS 標頭，可用於腳本、後端服務、CI 工作和瀏覽器開發工具。

GEThttps://genaddr.com/api/v1/address

快速開始

傳送 GET 請求即可使用。公共端點不需要 API Key。

curl "https://genaddr.com/api/v1/address"

查詢參數

countryUS

ISO-3166 alpha-2 國家/地區代碼。支援：US, CA, GB, AU, DE, FR, ES, IT, NL, JP, KR, CN, TW, HK, SG, TH, PH, MY, TR, VN, IN。

admin1隨機

州、省、都道府縣或地區代碼。別名：state、region、province。

city隨機

精確城市名稱。支援 Los-Angeles 這類 URL 友善格式。

count1

產生 1 到 100 筆記錄。多筆記錄會回傳 addresses 陣列。

has_number0

相容需要門牌號街道地址的整合。別名：hasNumber。

請求範例

兩筆加州地址

curl "https://genaddr.com/api/v1/address?country=US&state=CA&count=2"

含門牌號的洛杉磯地址

curl "https://genaddr.com/api/v1/address?country=US&state=CA&city=Los-Angeles&has_number=1"

國際測試資料

curl "https://genaddr.com/api/v1/address?country=JP&admin1=40&city=Tokyo&count=3"

程式碼範例

可在前端工具、後端工作、自動化測試和種子腳本中呼叫地址產生器 API。這些範例只請求合成測試資料。

JavaScript fetch

const res = await fetch("https://genaddr.com/api/v1/address?country=US&state=CA&count=5");
const data = await res.json();
console.log(data.addresses ?? [data.address]);

Python requests

import requests

res = requests.get("https://genaddr.com/api/v1/address", params={"country": "DE", "count": 3})
res.raise_for_status()
print(res.json())

OpenAPI 結構

下載機器可讀的 OpenAPI 結構，用於產生客戶端、API 目錄、文件工具和契約測試。

查看 openapi.json

回應範例

{
  "status": "ok",
  "meta": {
    "apiVersion": "v1",
    "count": 1,
    "country": "US",
    "admin1": "CA",
    "city": "Los Angeles",
    "hasNumber": true,
    "datasetVersion": "2026-06-02"
  },
  "address": {
    "country": "US",
    "countryName": "United States",
    "fullName": "Quinn Hayes",
    "street": "9942 Willow Creek Road",
    "city": "Los Angeles",
    "admin1Code": "CA",
    "postal": "90001",
    "phone": "+1 562 907 2402",
    "email": "quinn.hayes@example.com",
    "unverifiable": {
      "street": { "unverifiable": false, "source": "openaddresses" }
    }
  }
}

回應欄位

每筆記錄包含地址、個人資料、電話和傳真、就業資料、付款測試欄位、登入欄位、User-Agent、地圖 URL 與來源標記。

開發者使用場景

QA 自動化為 Playwright、Cypress、Selenium 和 API 整合測試產生可重複的地址記錄。
資料庫種子資料用合成地址、電話、信箱、公司和個人資料欄位填充測試或預發布資料庫。
結帳驗證在不使用客戶資料的情況下測試配送、帳單、郵遞區號和電話號碼驗證流程。
展示和原型為儀表板、CRM 表格、註冊流程和後台工具填入逼真的範例資料。

限流與錯誤

公共呼叫依 IP 限制為每小時 600 次。回應包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 標頭。

400 unsupported_country - 國家/地區代碼不在資料集中。
404 not_found - 找不到匹配的州、地區或城市。
429 rate_limit_exceeded - 用戶端超過每小時限制。

負責任使用

API 回傳的所有個人資料皆為虛構，僅供開發與測試使用。請勿用於冒充、身分驗證、付款嘗試或非法用途。

常見問題