하위 카테고리 목록 조회

사업장의 업종을 분류하는 하위 카테고리의 전체 목록을 반환합니다. 이 계정에서는 약 6,000개의 항목을 반환하므로, 이를 변경이 드문 대규모 참조 목록으로 취급하고 생성하거나 업데이트할 때마다 인라인으로 호출하는 대신 한 번 가져와 캐시한 후 주기적으로 갱신합니다.

각 항목에는 다음이 포함됩니다:

• databaseId: 사업장을 생성하거나 업데이트할 때 subCategoryId로 전달하고, 추가 카테고리의 경우 additionalCategoryIds 배열에 포함할 정수입니다.
• id: 동일한 레코드의 Base64로 인코딩된 Relay 식별자입니다.
• key: 카테고리 이름을 URL에 적합한 형태로 만든 슬러그입니다.
• name: 사람이 읽을 수 있는 레이블입니다.
• primary: 해당 카테고리를 사업장의 기본 하위 카테고리로 사용할 수 있는지 여부입니다.

사업장 생성 전 카테고리 확인

사업장을 온보딩할 때는 일반적으로 업종을 자유 형식 텍스트("3D 프린팅 서비스")로 알고 있지만, createLocation에는 숫자형 subCategoryId가 필요합니다. 이 목록을 한 번 조회하고 자체 코드에서 name → databaseId 매핑을 만든 다음, 생성 시점에 id를 조회하는 방식으로 처리합니다.

const res = await fetch('https://listingsapi.com/api/v4/sub-categories', {  headers: { Authorization: 'API ' + process.env.LISTINGSAPI_KEY },});const { data } = await res.json();const byName = new Map(data.subcategories.map((s) => [s.name.toLowerCase(), s.databaseId])); const subCategoryId = byName.get('3d printing service'); // 4589

사업장에 카테고리를 2개 이상 지정하려면 subCategoryId에 기본 카테고리를 전달하고 additionalCategoryIds에 추가 카테고리 id를 최대 9개 전달합니다. 이러한 필드가 어떻게 사용되는지는 사업장 생성 및 사업장 업데이트를 참조합니다.

응답은 페이지를 나누지 않은 단일 배열입니다. 다른 호출과 마찬가지로 계정의 요청 빈도 제한에 포함되므로 사업장마다 다시 가져오는 대신 캐시하며, 429 응답에는 Retry-After 헤더가 포함됩니다.