実在住宅住所ジェネレーター 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 · stringOptional IPv4 or IPv6 address; omitted means the request 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 country code.

field任意 · query · string · 既定値: cityCatalog field to return.

q任意 · query · stringOptional case-insensitive search text.

region任意 · query · stringExact parent region value.

regionId任意 · query · stringStable parent region ID.

cityId任意 · query · stringStable parent city ID.

residential任意 · query · boolean · 既定値: falseRestrict counts to published residential records.

cursor任意 · query · stringOpaque cursor returned by the previous page.

limit任意 · query · integer · 既定値: 100 · 20-200Page size from 20 through 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 country code.

region任意 · query · stringExact first-level region value.

regionId任意 · query · stringStable region ID from location search.

city任意 · query · stringExact city value.

cityId任意 · query · stringStable city ID from location search.

district任意 · query · stringExact district value where supported.

districtId任意 · query · stringStable district ID from location search.

postcode任意 · query · stringExact postcode value.

postcodeId任意 · query · stringStable postcode ID from location search.

mode任意 · query · stringUse ip-region to match the request or supplied IP.

ip任意 · query · stringIPv4 or IPv6 used with ip-region mode.

q任意 · query · stringText that must occur in the selected address components.

strategy任意 · query · string · 既定値: randomSelection strategy; both modes select from the synchronized database.

residential任意 · query · boolean · 既定値: trueLegacy compatibility flag; generation always returns residential records.

seed任意 · query · stringOptional reproducible random seed.

requestId任意 · query · stringCaller-provided request correlation ID.

リクエスト例

curl "https://address.example/api/v1/generate?country=VN&region=Ho%20Chi%20Minh%20City&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=VN&region=Ho%20Chi%20Minh%20City&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=VN&region=Ho%20Chi%20Minh%20City&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": "VN",
    "mode": "residential",
    "sourcesTried": [
      "address-pool-v2"
    ],
    "result": {
      "address": {
        "id": "address-id",
        "countryCode": "VN",
        "formattedAddress": "Example published residential address"
      },
      "context": {
        "countryCode": "VN",
        "gender": "female",
        "dateOfBirth": "1995-07-28",
        "addressRegionCode": "VN-SG",
        "addressRegionName": "Ho Chi Minh City",
        "syntheticBirthRegistrationRegion": {
          "code": "079",
          "name": "Synthetic Ho Chi Minh City",
          "provenance": "synthetic",
          "officialStatus": "not_official"
        },
        "locale": "vi",
        "currency": "VND"
      },
      "identityDocuments": [
        {
          "type": "VN_CCCD",
          "number": "079195123456",
          "testDataOnly": true,
          "issued": false,
          "verificationStatus": "not_verified",
          "unique": false,
          "verifiable": false,
          "metadata": {
            "regionSemantics": "synthetic_birth_registration_region",
            "regionProvenance": "synthetic",
            "regionOfficialStatus": "not_official",
            "deterministic": true,
            "realWorldIssued": false,
            "unique": false,
            "verifiable": false
          }
        }
      ]
    }
  }
}

POST/api/v1/generate/batch

スコープ: generate

構造化フィルター、除外条件、一意性制御で最大 50 件の住宅住所を生成します。

パラメーター

count必須 · body · integer · 1-50Number of addresses to generate.

filters必須 · body · objectCountry and exact administrative, postcode, or text filters.

options任意 · body · objectRandomness, uniqueness, strategy, and request correlation options.

excludeAddressIds任意 · body · arrayAddress IDs that must not be returned.

リクエスト例

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": "VN",
    "region": "Ho Chi Minh City"
  },
  "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":"VN","region":"Ho Chi Minh City"},"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": "VN",
      "region": "Ho Chi Minh City"
    },
    "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": "VN",
          "formattedAddress": "Example published residential address"
        },
        "context": {
          "countryCode": "VN",
          "gender": "female",
          "dateOfBirth": "1995-07-28",
          "addressRegionCode": "VN-SG",
          "addressRegionName": "Ho Chi Minh City",
          "syntheticBirthRegistrationRegion": {
            "code": "079",
            "name": "Synthetic Ho Chi Minh City",
            "provenance": "synthetic",
            "officialStatus": "not_official"
          },
          "locale": "vi",
          "currency": "VND"
        },
        "identityDocuments": [
          {
            "type": "VN_CCCD",
            "number": "079195123456",
            "testDataOnly": true,
            "issued": false,
            "verificationStatus": "not_verified",
            "unique": false,
            "verifiable": false,
            "metadata": {
              "regionSemantics": "synthetic_birth_registration_region",
              "regionProvenance": "synthetic",
              "regionOfficialStatus": "not_official",
              "deterministic": true,
              "realWorldIssued": false,
              "unique": false,
              "verifiable": false
            }
          }
        ]
      }
    ]
  }
}

GET/api/v1/locations/hierarchy

スコープ: read

国、地域、都市の直下にある行政区または郵便番号を一覧表示します。

パラメーター

country必須 · query · stringISO 3166-1 alpha-2 country code.

childType必須 · query · stringChild catalog type to return.

parentType任意 · query · string · 既定値: countryType of parent identified by parentId.

parentId任意 · query · stringStable region or city ID; omit for a country parent.

q任意 · query · stringOptional child-name search text.

residential任意 · query · boolean · 既定値: trueInclude residential availability and disable uncovered options.

cursor任意 · query · stringOpaque cursor returned by the previous page.

limit任意 · query · integer · 既定値: 100 · 20-200Page size from 20 through 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

有効な国の 3 つの同期完了ルールを返します。

パラメーター

country任意 · query · stringOptional ISO country code filter.

includeComplete任意 · query · boolean · 既定値: trueInclude countries that already satisfy all three rules.

リクエスト例

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 · stringAddress ID returned by generate or batch generation.

リクエスト例

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 · stringAddress ID returned by generate.

targetLocale必須 · body · stringTarget display locale.

リクエスト例

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