Listings APIListings API
로그인

국가, 주 및 카테고리 조회

사업장을 생성하기 전에 지원되는 국가와 주 코드를 가져오고, 비즈니스 카테고리에 해당하는 숫자 id를 찾고, 요금제에 포함된 게시 플랫폼을 확인합니다.

사업장을 생성하려면 API에서 가져온 3가지 값이 필요합니다. API가 허용하는 countryIso 및 stateIso, 숫자 subCategoryId, 그리고 게시 플랫폼을 제한하려는 경우 요금제에 포함된 사이트 id입니다. 이 값들은 3개의 카탈로그 엔드포인트에서 제공합니다. 3개 모두 페이지네이션 없이 일반 배열을 반환합니다.

1. 국가 및 주 코드 목록 조회

GET /countries는 지원되는 모든 국가를 각 국가의 ISO 코드, hasCity 플래그 및 states 배열과 함께 반환합니다. iso 값은 생성 및 업데이트 시 countryIso와 stateIso에 사용합니다. Python SDK에서는 이를 client.countries()로, Node SDK에서는 client.fetchCountries()로 제공합니다.

Countries
curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "iso": "AU",        "name": "Australia",        "hasCity": true,        "states": [          { "id": "139", "iso": "VIC", "name": "Victoria" },          { "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "iso": "BE",        "name": "Belgium",        "hasCity": true,        "states": []      }    ]  }}

hasCity: true는 생성 시 city가 필수임을 의미하며, false인 경우 전송한 도시는 제외됩니다. stateRequired: true는 stateIso가 필수이며 해당 국가의 states 중 하나여야 함을 의미하고, false인 경우에는 생략합니다. hasPostalCode: true는 해당 국가에서 우편번호를 사용함을 의미하므로 주소와 함께 postalCode를 전송합니다. 국가 엔드포인트에서 각 플래그를 설명합니다.

2. 카테고리 id 찾기

GET /sub-categories는 전체 카테고리 카탈로그를 반환합니다. subCategoryId로 전송하는 값은 base64 id가 아니라 정수인 databaseId입니다. 예를 들어 음식점은 1432입니다. 서버 측 검색 매개변수가 없으므로 자체 코드에서 이름으로 목록을 필터링합니다.

Find a category
curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.subcategories[] | select(.name | test("restaurant"; "i")) | {databaseId, name, primary}'
JSON
{  "data": {    "subcategories": [      {        "databaseId": 1432,        "id": "U3ViQ2F0ZWdvcnk6MTQzMg==",        "key": "restaurants",        "name": "Restaurants",        "primary": true      }    ]  }}
필드용도
databaseIdsubCategoryId로 전송하거나 최대 9개의 보조 카테고리를 지정하기 위해 additionalCategoryIds에 포함하여 전송하는 정수입니다.
name선택기에 표시하고 일치 여부를 확인하는 데 사용하는 사람이 읽을 수 있는 레이블입니다.
keyURL에 적합한 형식으로 된 이름의 슬러그이며, 이름이 변경되어도 유지됩니다.
primary해당 카테고리를 사업장의 기본 하위 카테고리로 사용할 수 있는지 여부입니다. subCategoryId에는 true 항목만 선택합니다.

3. 요금제에 포함된 게시 플랫폼 확인

GET /plan-sites는 요금제에 포함된 모든 게시 플랫폼을 숫자 id, url, 등록을 허용하는 국가 및 hideAddress를 적용하는 국가와 함께 나열합니다. 이 id만 생성 시 enabledSiteIds와 업데이트 시 submissionDisabledSiteIds에 사용할 수 있는 유효한 값입니다. 해당 사업장의 등록을 허용하는 게시 플랫폼만 제시하도록 사업장이 위치한 국가를 기준으로 필터링합니다.

Plan sites
curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.supportedCountries | index("US")) | {id, name, url}'
JSON
{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 2,        "name": "Yelp",        "url": "yelp.com",        "supportedCountries": ["US", "CA", "GB", "DE", "FR"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]      }    ]  }}

여기서는 두 국가 배열을 모두 축약했으며, 실제 응답에는 사이트당 50개 이상의 코드가 포함될 수 있습니다. 국가를 허용하는 게시 플랫폼이라도 도로명 주소가 없는 등록 정보는 거부할 수 있으므로, 서비스 지역 비즈니스의 경우 hideAddressSupportedCountries도 확인합니다.

4. 조회 결과 캐시

3개 카탈로그는 모두 거의 변경되지 않고 페이지네이션도 사용하지 않으므로, 시작 시 각각 한 번씩 가져와 메모리나 작은 테이블에 저장하고 정해진 주기에 따라 갱신합니다. 사업장을 생성할 때마다 이 엔드포인트들을 호출하면 새 데이터 없이 요청 빈도 제한만 소모합니다. Launch 요금제에서는 분당 요청 10회 중 3회에 해당합니다.

카탈로그규모갱신 시점
국가수십 개 국가, 수백 개 주드물게 갱신합니다. 하루에 한 번이면 충분합니다.
하위 카테고리약 6,000개 항목매일 또는 알 수 없는 subCategoryId로 인해 생성에 실패할 때 갱신합니다.
요금제에 포함된 사이트수십 개 게시 플랫폼목록의 범위가 요금제로 한정되므로 요금제 변경 시 갱신합니다.

하위 카테고리에는 소문자 name에서 databaseId로의 매핑을, 국가에는 countryIso에서 states로의 매핑을 만듭니다. 생성 호출 전에 캐시를 기준으로 주소를 검증하여, 지원되지 않는 countryIso(SY10036) 또는 누락된 city(SY10126)를 요청이 전송되기 전에 애플리케이션에서 감지하도록 합니다.

다음 단계