통합 방법 선택

애플리케이션의 아키텍처와 통합 요구 사항에 따라 REST API, Python 및 Node SDK, MCP 서버, 웹훅을 비교합니다.

모든 통합 방법은 동일한 API 키와 기본 URL인 https://listingsapi.com/api/v4를 사용합니다. API 요청에는 REST API 또는 SDK를, 이벤트 기반 업데이트에는 웹훅을, AI 에이전트의 도움을 받는 통합에는 MCP 서버를 사용할 수 있습니다.

1. API 호출 방법 선택

REST API. REST API를 사용하면 HTTP를 통해 모든 엔드포인트에 직접 액세스할 수 있습니다. 애플리케이션에서 응답을 파싱하고, 두 가지 페이지네이션 방식을 모두 처리하고, errors[] 배열에서 API 오류를 확인해야 합니다.

Python SDK. pip install listingsapi로 Python SDK를 설치합니다. SDK는 client.locations 및 client.reviews와 같은 인터페이스를 통해 리소스 클래스를 제공합니다. auto_paging_iter()로 커서 페이지네이션을 처리하고, 429 또는 5xx 응답을 반환하는 요청을 재시도하며, API 요청을 보내기 전에 locations.add()에서 사업장 페이로드의 유효성을 검사합니다. Python SDK를 참조합니다.

Node SDK. npm install listingsapi-js로 Node SDK를 설치합니다. Node.js 18 이상이 필요하며, TypeScript 타입 정의를 포함하고, 런타임 의존성이 없습니다. SDK 메서드는 client.fetchAllLocations()처럼 클라이언트 인스턴스에서 바로 호출합니다. 페이지네이션된 모든 결과를 단일 응답으로 가져오려면 fetchAll: true를 설정합니다. 숫자 ID는 API 요청이 전송되기 전에 자동으로 Base64로 인코딩됩니다. Node SDK를 참조합니다.

MCP 서버. Streamable HTTP를 사용하여 Claude, ChatGPT, Cursor, Gemini와 같은 AI 클라이언트를 https://listingsapi.com/mcp의 ListingsAPI MCP 서버에 연결합니다. 로컬 MCP 서버를 설치할 필요가 없습니다. 서버는 ListingsAPI 문서 검색, REST 엔드포인트 탐색, 지원되는 API 작업 실행을 위한 도구를 제공합니다. 인증에는 API 키 또는 OAuth를 사용합니다. /dashboard/mcp를 열어 클라이언트 구성, 사용 가능한 MCP 도구, 각 도구에 필요한 API 키 권한 수준을 확인합니다. MCP로 AI 에이전트 연결하기를 참조합니다.

웹훅. REST API, SDK 또는 MCP 서버와 함께 웹훅을 사용하여 이벤트 기반 업데이트를 수신합니다. 사업장, 등록 정보, 리뷰 또는 게시물이 변경되면 ListingsAPI는 계정에 구성된 웹훅 URL로 HTTP POST 요청을 보냅니다. 이를 통해 애플리케이션은 업데이트를 확인하기 위해 API를 폴링하지 않고도 변경 사항을 처리할 수 있습니다. 웹훅 개요를 참조합니다.

2. 인증 모델 이해

REST API와 SDK는 API 키를 사용하여 요청을 인증합니다. API 인증 방식을 사용하여 HTTP Authorization 요청 헤더에 키를 전달합니다:

Authorization: API <YOUR_API_KEY>

API 키에는 Read(읽기) 또는 Write(쓰기) 액세스 권한이 있습니다. Read 키는 조회 및 보고서를 포함한 읽기 작업에 액세스할 수 있습니다. 리소스를 생성하거나 업데이트하는 작업에는 Write 키가 필요합니다. 쓰기 엔드포인트에 Read 키를 전송하면 해당 엔드포인트는 오류 코드 SY90016과 함께 HTTP 400을 반환합니다.

API 키의 범위는 하나의 계정으로 제한됩니다. 동일한 계정의 키로 수행한 요청은 동일한 계정 수준의 요청 빈도 제한 할당량을 소모합니다.

MCP 서버는 OAuth 인증도 지원합니다. MCP 클라이언트는 API 키를 제공하는 대신 브라우저에서 OAuth를 사용하여 인증할 수 있습니다. REST API 및 SDK 요청은 Authorization 헤더를 사용하여 인증합니다. 자세한 구성 방법은 인증 문서를 참조합니다.

3. 페이지네이션 모델 이해하기

REST 목록 엔드포인트는 커서 기반 또는 오프셋 기반 페이지네이션을 사용합니다. SDK는 이러한 페이지네이션 모델을 추상화합니다.

커서 기반 엔드포인트는 first와 after를 받습니다. 결과는 edges[].node를 통해 반환되며, pageInfo.endCursor는 다음 요청에 사용할 커서를 제공합니다.

오프셋 기반 엔드포인트는 page와 perPage를 받습니다. 결과는 records[]에 반환되며, pageInfo.totalRecords는 사용 가능한 전체 레코드 수를 나타냅니다.

방식	매개변수	페이로드	사용 대상
커서	`first`, `after`	`edges[].node`, `pageInfo.endCursor`, `pageInfo.hasNextPage`	사업장, 사업장 검색, 리뷰
오프셋	`page`, `perPage`	`records[]`, `pageInfo.totalRecords`, `pageInfo.totalPages`	연결된 계정, 제안, 게시물, 중복 집계
없음		일반 배열	국가, 하위 카테고리, 요금제 사이트, 특정 사업장의 사진

다음 예제는 3가지 통합 방식을 사용하여 동일한 사업장 목록 조회 작업을 수행합니다. cURL 구현에서는 애플리케이션이 API 응답 구조를 직접 파싱해야 합니다.

List locations

curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

모든 통합 방식에서 API 오류는 errors[] 배열에 반환되며, 각 오류 메시지 앞에는 SY 오류 코드가 붙습니다. 쓰기 요청은 success: false와 함께 HTTP 200을 반환할 수 있으므로, 작업이 성공했다고 판단하기 전에 응답 본문을 확인해야 합니다.

계정이 요청 빈도 제한을 초과하면 API는 Retry-After 헤더와 함께 HTTP 429를 반환합니다. Launch 요금제는 분당 최대 10개의 요청을 지원합니다. 자세한 내용은 오류 코드 및 요청 빈도 제한 문서를 참조합니다.

4. 웹훅과 폴링 중 선택하기

모든 사업장을 매일 밤 동기화하는 경우처럼 애플리케이션이 정해진 일정에 따라 리소스 상태를 필요로 하거나, 필요한 이벤트가 웹훅을 지원하지 않는 경우에는 폴링을 사용합니다. 새 리뷰 수신, 등록 정보 상태 변경, Google 게시물 거부와 같은 변경 사항을 발생 즉시 처리해야 하는 경우에는 웹훅을 사용합니다.

/dashboard/webhooks에서 계정마다 웹훅 URL을 1개씩 설정합니다. 각 웹훅 요청에는 다음 형식의 X-ListingsAPI-Signature 헤더가 포함됩니다.

X-ListingsAPI-Signature: sha256=<base64 HMAC>

웹훅 엔드포인트는 5초 이내에 2xx 응답을 반환해야 합니다. 전송에 실패해도 재시도하지 않습니다.

웹훅 이벤트를 트리거로 사용하여 API에서 현재 리소스 상태를 조회합니다. 웹훅 전송은 재시도하지 않으므로, 누락되었을 수 있는 업데이트를 감지하기 위해 정기적인 대조 프로세스를 실행합니다. 구현 예제는 웹훅으로 이벤트에 대응하기를 참조합니다.

5. 한눈에 비교하기

옵션	적합한 용도	인증	페이지네이션 자동 처리 여부	자세히 보기
REST	모든 엔드포인트, 선호하는 기술 스택 및 HTTP 클라이언트	API 키 헤더	아니요, 커서나 페이지를 직접 따라가야 합니다	시작하기
Python SDK	백엔드 작업, 데이터 파이프라인, 스크립트	`LISTINGSAPI_KEY`에서 가져온 API 키	예, `SyncPage` 및 `auto_paging_iter()`	Python SDK
Node SDK	TypeScript 서비스, 서버리스, 대시보드	`LISTINGSAPI_KEY`에서 가져온 API 키	예, `fetchAll: true`	Node SDK
MCP	Claude, Cursor 및 기타 AI 어시스턴트	API 키 또는 OAuth	예, 도구가 전체 결과를 반환합니다	`/dashboard/mcp`
웹훅	수초 이내에 변경 사항에 대응	전송마다 포함되는 HMAC 서명	해당 없음, 전송당 이벤트 1개	웹훅 개요

다음 단계

사업장 추가하기: 선택한 옵션으로 첫 쓰기 호출을 수행합니다.
웹훅으로 이벤트에 대응하기: 서명을 검증하는 수신기를 구축합니다.
Python SDK 및 Node SDK: 설치 및 설정을 진행하고 메서드 표를 확인합니다.
인증, 요청 빈도 제한 및 오류 코드: 모든 옵션에 공통으로 적용되는 3가지 참조 문서입니다.