인증
상태 확인, 준비 상태 확인 및 OpenAPI를 제외한 모든 엔드포인트에는 관리자 콘솔에서 만든 Bearer Token이 필요합니다. 읽기 또는 생성 범위, 분당 제한 및 만료를 설정할 수 있습니다.
Authorization: Bearer YOUR_API_TOKEN
GET/api/v1/health
범위: publicAPI 프로세스의 사용 가능 여부를 확인합니다.
요청 예시
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);
GET/api/v1/ready
범위: publicAPI와 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
}
]
}
요청 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"
}
}
지역, 도시, 구역 또는 우편번호를 페이지 단위로 검색합니다.
매개변수
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®ionId=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®ionId=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®ionId=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=US®ion=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®ion=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®ion=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"
}
}
}
}
구조화 필터, 제외 조건 및 고유성 제어로 최대 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": "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"
}
}
]
}
}
국가, 지역 또는 도시의 바로 아래 행정 구역이나 우편번호를 조회합니다.
매개변수
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활성화된 국가의 세 가지 동기화 완료 규칙을 반환합니다.
매개변수
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
}
}
}
]
}
}
생성 결과의 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"
}
}
}
동기화된 주소를 지원되는 표시 언어로 번역합니다.
매개변수
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