Node SDK
Node 18+용 공식 Listings API TypeScript 클라이언트입니다. 의존성이 없으며 자동 페이지네이션과 타입 정의를 기본 제공합니다.
listingsapi-js은 Listings API v4의 공식 Node.js/TypeScript 클라이언트입니다. 단일 평면 구조의 클라이언트에서 사업장, 디렉터리 등록 정보, 리뷰, 게시물, 사진, 프로필 분석 데이터를 관리하며, 커서 기반 페이지네이션, 자동 ID 인코딩, 내장 재시도 기능, 타입이 지정된 오류를 기본으로 제공합니다.
설치
npm install listingsapi-js인증
Listings API 개발자 대시보드의 API Keys → New key에서 API 키를 발급받습니다.
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from envconst explicit = new ListingsAPI({ apiKey: 'your-api-key' }); // or pass it directly생성자에는 baseUrl(기본값 https://listingsapi.com), timeout(기본값 240000 ms), maxRetries(기본값 2)도 전달할 수 있습니다. 설정을 참조합니다.
간단한 예제
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); const result = await client.fetchAllLocations({ first: 5 });if (!Array.isArray(result)) {for (const location of result.locations) { console.log(location.name, '--', location.city);}}리소스
모든 메서드는 클라이언트 인스턴스에 있습니다:
브랜드, 연결된 소셜 계정, Facebook, Instagram, X, LinkedIn, Pinterest에 게시하는 게시물을 관리하는 Social API는 아직 이 SDK에서 지원하지 않으므로, Social REST 참조 문서에 따라 직접 호출합니다.
페이지네이션
목록을 반환하는 메서드는 커서 기반 페이지네이션을 지원합니다.
// Single pageconst page = await client.fetchAllLocations({ first: 25 });if (!Array.isArray(page)) {console.log(page.locations); // Location[]console.log(page.pageInfo); // { hasNextPage, hasPreviousPage, startCursor, endCursor } // Next pageif (page.pageInfo.hasNextPage) { const next = await client.fetchAllLocations({ first: 25, after: page.pageInfo.endCursor!, });}} // Auto-paginate: returns a flat Location[]const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });searchLocations과 fetchInteractions은 같은 패턴을 따릅니다. 기본적으로 페이지 객체를 반환하며, fetchAll: true를 사용하면 평면 배열을 반환합니다.
ID 인코딩
사업장 ID를 전달하는 모든 곳에서 숫자형 ID를 사용할 수 있으며, SDK가 이를 자동으로 base64 인코딩합니다. 이미 인코딩된 ID는 그대로 허용하며, 직접 사용해야 할 경우를 위해 인코더도 내보냅니다.
import { encodeLocationId } from 'listingsapi-js'; // These are equivalentawait client.fetchPremiumListings(16808);await client.fetchPremiumListings('TG9jYXRpb246MTY4MDg='); encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='오류 처리
모든 SDK 오류는 ListingsAPIError을 상속합니다. 플랫폼이 API 실패를 HTTP 상태로 보고하든 HTTP 200 본문에 포함하여 보고하든, API 실패 시 APIError 또는 그 하위 클래스 중 하나를 발생시킵니다(유효하지 않은 토큰과 쓰기 유효성 검사 오류는 errors[] 페이로드로 전달되며, 쓰기 작업은 success: false을 보고할 수 있습니다). SDK는 이러한 모든 경우에 예외를 발생시키므로 success 플래그를 직접 확인할 필요가 없습니다. 네트워크 실패 시 APIConnectionError를 발생시킵니다.
모든 APIError에는 statusCode, responseBody, code(첫 번째 플랫폼 오류 코드, e.g. "SY10005"), errors(각 항목은 { code, message, context }로 정규화됨)이 포함됩니다.
import { ListingsAPI, APIError, RateLimitError } from 'listingsapi-js'; const client = new ListingsAPI(); try {await client.fetchAllLocations();} catch (error) {if (error instanceof RateLimitError) { console.log(error.retryAfter); // seconds to wait} else if (error instanceof APIError) { console.log(error.statusCode); // 401, 404, 500, or 200 for payload-level errors console.log(error.code); // first platform code, e.g. 'SY10005' console.log(error.errors); // [{ code, message, context }, ...]}}클라이언트는 429 및 5xx 응답을 받으면 자동으로 재시도합니다(기본 2회 시도, Retry-After 준수). 재시도 패턴과 상태 코드 안내는 오류 처리를 참조합니다.