Listings APIListings API
로그인
GET/api/v4/countries

지원되는 국가 및 주 목록 조회

Listings API가 지원하는 모든 국가와 해당 국가의 주/도, 사업장을 생성하거나 업데이트할 때 사용하는 ISO 코드, 각 국가에서 필수로 요구하거나 검사하는 주소 필드를 반환합니다.

API 키가 필요합니다. 헤더 형식과 키 교체는 인증을 참고하세요.

매개변수

이 엔드포인트는 매개변수를 받지 않습니다.

응답

200List of supported countries, each with its states and ISO codes. The live response is trimmed here to the United States, with three of its states.
Response
{  "data": {    "supportedCountries": [      {        "databaseId": 233,        "hasCity": true,        "id": "Q291bnRyeToyMzM=",        "iso": "US",        "name": "United States",        "hasPostalCode": true,        "stateRequired": true,        "states": [          { "countryId": 233, "id": "3542", "iso": "CA", "name": "California" },          { "countryId": 233, "id": "3537", "iso": "NY", "name": "New York" },          { "countryId": 233, "id": "3524", "iso": "TX", "name": "Texas" }        ]      }    ]  }}
401Unauthenticated, missing or invalid API key.
500Internal server error.

Listings API가 사업장 데이터에 대해 지원하는 국가와 행정 구역(주, 도, 준주)의 전체 목록을 반환합니다. 각 국가 항목에는 ISO 코드(iso), Relay id, 숫자형 databaseId, states 배열, 해당 국가에서 사업장 주소를 검사하는 방식을 나타내는 3개의 플래그가 포함됩니다. 각 주에는 자체 iso 및 숫자형 id가 포함됩니다. Listings API에서 행정 구역을 구분하지 않는 국가의 경우 빈 states 배열을 반환합니다.

국가별 주소 규칙

플래그truefalse
hasCity생성 시 city는 필수입니다(SY10126).해당 국가의 주소 체계에는 도시 단위가 없습니다. 전송한 city 값은 저장되지 않습니다.
stateRequiredstateIso는 필수이며 해당 국가의 states 중 하나여야 합니다(SY10010).stateIso는 생략합니다. 이 중 일부 국가에는 states 목록이 있지만, 전송한 값은 검사 없이 저장됩니다.
hasPostalCode해당 국가는 우편번호를 사용합니다. 주소와 함께 postalCode를 전송합니다.해당 국가에는 우편번호 체계가 없습니다. postalCode는 생략합니다.

postalCode는 모든 국가에서 선택 사항이지만, hasPostalCode가 true인 경우에는 항상 전송합니다. 일부 게시 플랫폼에서는 지도 핀을 배치하는 데 이 값이 필요하기 때문입니다. 전송한 값이 해당 국가의 형식에 맞는지 검사합니다(SY10014). 사업장에 hideAddress: true가 있으면 도시 및 주 검사를 건너뜁니다.

사용 사례: 주소 드롭다운 채우기. 앱 시작 시 이 데이터를 한 번 가져와 캐시합니다. name/iso를 기반으로 국가 선택기를 표시하고, 국가를 선택하면 해당 국가의 states로 주 선택기를 채웁니다. iso 값은 create-location 및 update-location 엔드포인트의 countryIso 및 stateIso 필드에 그대로 사용할 수 있습니다.

사용 사례: 제출 전 주소 유효성 검사. create-location을 호출하기 전에 대상 countryIso가 이 목록에 있는지, stateRequired가 true일 때 stateIso가 해당 국가 아래에 있는지, hasCity가 true일 때 city가 설정되어 있는지 확인합니다. 여기서 지원되지 않는 코드를 감지하면 생성 호출에서 400을 받는 대신 클라이언트 측에서 명확한 메시지를 표시할 수 있습니다. 전체 응답은 지원되는 모든 국가를 포함하므로 크기가 크며, 위 예시는 항목 1개만 포함하도록 줄였습니다. 쿼리 매개변수는 없으며, 엔드포인트는 항상 전체 목록을 반환합니다.

Request
curl -X GET 'https://listingsapi.com/api/v4/countries' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground