快速入門
使用 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 }, ...]}}對於非 2xx 回應、平台以 HTTP 200 傳回的錯誤酬載，以及回報 success: false 的寫入操作，SDK 都會擲出具有特定型別的錯誤。收到 429 和 5xx 回應時，SDK 也會自動重試。如需重試模式和狀態碼的使用指引，請參閱錯誤處理。