クイックスタート
TypeScriptでListings APIに接続し、拠点の一覧取得、拠点の作成、レビューへの返信を行います。
1. API キーを設定する
Listings API 開発者ダッシュボードの API Keys → New key からキーを取得します。
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 のレスポンスに対して自動的に再試行します。再試行のパターンとステータスコードに関する説明は、エラー処理を参照してください。