Listings APIListings API
로그인

보조 API

지원되는 국가와 주, 하위 카테고리 카탈로그, 요금제에 포함된 게시 플랫폼 사이트를 조회하는 모든 보조 API 엔드포인트와 각 엔드포인트의 cURL, Python 및 Node 예제입니다.

보조 엔드포인트는 API의 나머지 부분에서 유효성 검사의 기준으로 사용하는 3가지 참조 카탈로그를 제공합니다. 여기에는 지원되는 국가와 주, 사용 가능한 비즈니스 카테고리, 요금제에 포함된 게시 플랫폼 디렉터리가 있습니다. 3가지 모두 읽기 전용이고 페이지네이션 없이 전체 항목을 반환하므로 Read(읽기) 키만으로 충분하며, 페이지네이션보다 캐싱이 더 중요합니다.

엔드포인트 한눈에 보기

메서드경로기능참조
GET/countries지원되는 모든 국가와 각 국가의 주 및 ISO 코드입니다.지원되는 국가 및 주 목록 조회
GET/sub-categories약 6,000개 항목으로 구성된 전체 비즈니스 카테고리 카탈로그입니다.하위 카테고리 목록 조회
GET/plan-sites요금제에 포함된 모든 게시 플랫폼 디렉터리입니다.요금제에 포함된 사이트 목록 조회

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

GET /countries

data.supportedCountries에 전체 카탈로그를 반환합니다. 각 국가에는 ISO 코드, base64 형식의 id, 숫자형 databaseId, 각 항목에 고유한 ISO 코드가 있는 states 배열, 그리고 주소 관련 플래그 3개인 hasCity(도시 필수), stateRequired(주 필수이며 states를 기준으로 유효성 검사), hasPostalCode(우편번호를 사용하는 국가)가 포함됩니다. 하위 행정 구역으로 나뉘지 않는 국가는 빈 states 배열을 반환합니다.

매개변수

이 엔드포인트는 매개변수를 받지 않습니다. 항상 전체 항목을 반환합니다.

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

필요한 값은 2개의 iso 필드에 있습니다. 생성 및 수정 시 국가의 iso는 countryIso가 되고, 주의 iso는 stateIso가 됩니다. 쓰기 작업 전에 이 목록을 기준으로 두 값의 유효성을 검사하면 서버 측 400 대신 자체 양식에서 명확한 메시지를 표시할 수 있습니다.

하위 카테고리 목록 조회

GET /sub-categories

data.subcategories에 약 6,000개의 카테고리 레코드를 페이지네이션 없이 하나의 배열로 반환합니다. 이 조회를 통해 자유 형식 텍스트로 알고 있는 업종을 사업장 쓰기 작업에 필요한 숫자형 id로 변환할 수 있습니다.

매개변수

없습니다. 호출할 때마다 전체 카탈로그가 반환됩니다.

Subcategories
curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "subcategories": [      {        "databaseId": 4589,        "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==",        "key": "3d-printing-service",        "name": "3D printing service",        "primary": true      }    ]  }}

각 레코드에는 5개의 필드가 있으며, 사용할 필드는 사용처에 따라 달라집니다.

필드용도
databaseIdsubCategoryId의 값으로, 그리고 additionalCategoryIds 내부에 전달할 정수입니다.
id동일한 레코드의 base64 식별자입니다.
key이름을 URL에 적합한 형식으로 표현한 slug입니다.
name사용자에게 표시할 레이블입니다.
primary해당 카테고리를 사업장의 기본 하위 카테고리로 사용할 수 있는지 나타냅니다.

사업장에는 subCategoryId에 기본 카테고리 1개를, additionalCategoryIds에 추가 카테고리를 최대 9개까지 지정할 수 있습니다.

요금제에 포함된 사이트 목록 조회

GET /plan-sites

계정의 요금제에 포함된 모든 게시 플랫폼 디렉터리를 data.planSites에 반환합니다. 이 목록은 숫자형 사이트 id의 공식 기준이며, API의 다른 곳에서도 여기에 표시되는 id만 유효합니다.

매개변수

없습니다. 응답 범위는 계정의 요금제로 제한됩니다.

Plan sites
curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"
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": 184,        "name": "Facebook",        "url": "facebook.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      }    ]  }}

2개의 국가 배열은 서로 다른 질문에 답합니다. supportedCountries는 사이트에서 등록 정보를 받아들이는 국가를 나타내므로, 게시 플랫폼을 선택지로 제공하기 전에 사업장의 countryIso를 기준으로 필터링합니다. hideAddressSupportedCountries는 사이트에서 주소 숨김 설정을 적용하는 국가를 나타내며, 이는 서비스 지역 비즈니스에 필요한 기능입니다. 두 배열 모두 50개 이상의 코드를 포함할 수 있으며, 위 예제는 일부만 표시합니다.

사이트 id는 안정적으로 유지되므로 알아 두면 유용합니다. 1은 Google Maps이고 184는 Facebook이며, 이 두 게시 플랫폼은 대부분의 연결 흐름에서 대상이 됩니다.

별도의 엔드포인트가 아닙니다. 장소 작업 링크는 온라인 주문, 테이블 예약, 방문 예약과 같은 Google 버튼이며, 플랫폼은 이를 별도의 리소스가 아닌 사업장의 필드로 관리합니다. 생성 및 수정 시 placeActionLinks 배열을 통해 설정하고, 모든 사업장 조회 엔드포인트에서 조회할 수 있습니다.

각 항목에는 placeActionType과 uri가 필요하며, 선택 사항인 isPreferred 플래그로 유형별 최대 1개의 우선 링크를 지정할 수 있고, 수정 시 action의 값으로 add 또는 delete를 사용할 수 있습니다. 유효한 유형, 삭제 규칙, 동기화 동작은 모두 장소 작업 링크에 설명되어 있습니다.

발생할 수 있는 오류

코드 또는 상태의미해결 방법
401키가 누락되었거나 유효하지 않습니다.Authorization: API <YOUR_API_KEY>를 전송합니다.
Retry-After가 포함된 429이 카탈로그도 계정의 요청 빈도 제한을 함께 사용합니다.결과를 캐시합니다. 요청 빈도 제한을 참조하세요.
countries에서 발생하는 500잘못된 요청이 아니라 서버 측 오류입니다.재시도 간격을 늘려 가며 다시 시도합니다. 호출에서 수정할 사항은 없습니다.

이 엔드포인트는 모두 쓰기 작업을 수행하지 않으므로, 여기서는 Read 키로 호출해도 SY90016이 반환되지 않습니다. 전체 목록은 오류 코드에서 확인할 수 있습니다.

다음 단계