빠른 시작
TypeScript로 Listings API에 연결하고, 사업장 목록을 조회하고, 사업장을 생성하고, 리뷰에 답글을 작성합니다.
1. API 키 설정
Listings API 개발자 대시보드의 API 키 → 새 키에서 키를 발급받습니다.
export LISTINGSAPI_KEY="your-api-key"new ListingsAPI()은 환경에서 LISTINGSAPI_KEY을 자동으로 읽으며, apiKey을 명시적으로 전달할 수도 있습니다.
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, location.stateIso);}console.log('\nhasNextPage:', result.pageInfo.hasNextPage);}npx tsx quickstart.ts예상 출력:
Acme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NYAcme Dental Jersey City -- Jersey City NJ hasNextPage: falsefetchAllLocations은 기본적으로 locations과 pageInfo가 포함된 객체를 반환합니다. fetchAll: true을 전달하면 SDK가 커서를 따라 각 페이지를 자동으로 조회하고, 대신 중첩되지 않은 Location[]을 반환합니다.
const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });if (Array.isArray(all)) {console.log('Total: ' + all.length + ' locations');}3. 사업장 생성
API에는 name, city, countryIso, subCategoryId과 200자 이상의 description가 필요합니다. client.fetchSubcategories()에서 유효한 subCategoryId 값을 가져오고 각 항목의 databaseId을 사용합니다.
const created = await client.createLocation({name: 'Acme Dental',storeId: 'ACME-NYC-001',street: '123 Jump Street',city: 'New York',stateIso: 'NY',postalCode: '10013',countryIso: 'US',phone: '6443859313',subCategoryId: 1432,description: 'Acme Dental is a family-owned dental practice serving downtown New York since 2009. ' + 'Our team provides preventive checkups, cosmetic dentistry, orthodontics, and emergency care, ' + 'with same-day appointments, transparent pricing, and a patient-first approach on every visit.',});console.log(created);페이로드가 유효하지 않으면 API가 HTTP 200을 반환하더라도 SDK는 플랫폼의 오류 항목이 포함된 ValidationError 예외를 발생시킵니다. 확인할 수 있는 success 플래그는 없습니다.
4. 리뷰에 답글
사업장의 리뷰를 가져온 다음 상호작용 ID로 답글을 작성합니다. 숫자형 사업장 ID는 모든 곳에서 사용할 수 있으며, SDK가 자동으로 base64로 인코딩합니다.
const reviews = await client.fetchInteractions(16808, {startDate: '2026-01-01',endDate: '2026-06-30',first: 10,}); if (!Array.isArray(reviews)) {const unanswered = reviews.interactions.find( (review) => (review.responses ?? []).length === 0,);if (unanswered) { console.log(unanswered.rating, unanswered.content?.slice(0, 80)); await client.respondToReview( unanswered.id, 'Thank you for the kind words! We look forward to seeing you at your next visit.', );}}5. 오류 처리
import { ListingsAPI, APIError, AuthenticationError } from 'listingsapi-js'; const client = new ListingsAPI({ apiKey: 'bad-key' }); try {await client.fetchAllLocations();} catch (error) {if (error instanceof AuthenticationError) { console.log('Invalid API key. Check LISTINGSAPI_KEY.');} else if (error instanceof APIError) { console.log('Status:', error.statusCode); // can be 200 for payload-level errors console.log('Code:', error.code); // first platform code, e.g. 'SY10005' console.log('Errors:', error.errors); // [{ code, message, context }, ...]}}SDK는 2xx가 아닌 응답, 플랫폼이 HTTP 200과 함께 반환하는 오류 페이로드, success: false을 보고하는 쓰기 작업에 대해 유형이 지정된 예외를 발생시킵니다. 또한 429 및 5xx 응답에 대해 자동으로 재시도합니다. 재시도 패턴과 상태 코드 안내는 오류 처리를 참조합니다.