Listings APIListings API
登入

Node SDK

Listings API 的官方 TypeScript 用戶端，適用於 Node 18+，無外部相依套件，支援自動分頁，並隨附型別定義。

listingsapi-js 是 Listings API v4 的官方 Node.js/TypeScript 用戶端。它透過單一扁平結構的用戶端管理地點、目錄商家資訊、評論、貼文、相片及商家檔案分析資料，並內建游標式分頁、自動 ID 編碼、重試及具型別的錯誤。

安裝

bash
npm install listingsapi-js

驗證身分

在 Listings API 開發者儀表板的 API Keys → New key 取得您的 API 金鑰。

TypeScript
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 毫秒）及 maxRetries（預設為 2）。請參閱設定。

簡易範例

list_locations.ts
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);}}

資源

所有方法都位於用戶端實例上：

方法管理內容
fetchAllLocations, searchLocations, fetchLocationsByIds, fetchLocationsByStoreCodes, createLocation, updateLocation, archiveLocations, cancelArchiveLocations商家地點：列出、搜尋、建立、更新、封存
fetchInteractions, fetchReviewDetails, respondToReview, editReviewResponse, archiveReviewResponse, fetchReviewSettings, editReviewSettings, fetchReviewSiteConfig, fetchReviewPhrases, fetchReviewAnalyticsOverview, fetchReviewAnalyticsTimeline, fetchReviewAnalyticsSitesStats評論：列出、回覆、編輯及封存回覆、設定、片語及分析資料
bulkPublish, createAnnouncement, createEvent, createOffer, createPost, fetchPost, deletePost, fetchLocationPosts, fetchBulkPost, fetchLocationBulkPosts貼文：Google 和 Facebook 上的公告、活動及優惠
fetchPremiumListings, fetchVoiceListings, fetchDuplicateListings, fetchAllDuplicateListings, markListingsAsDuplicate, markListingsAsNotDuplicate目錄商家資訊：進階、語音、重複商家資訊
fetchGoogleAnalytics, fetchBingAnalytics, fetchFacebookAnalyticsGoogle、Bing 和 Facebook 商家檔案分析資料
fetchLocationPhotos, addLocationPhotos, removeLocationPhotos, starLocationPhotos, fetchPhotoUploadStatus地點相片
fetchConnectedAccounts, fetchConnectedAccountDetails, fetchConnectedAccountFolders, fetchConnectedAccountListings, fetchConnectionSuggestions, connectGoogleAccount, connectFacebookAccount, disconnectGoogleAccount, disconnectFacebookAccount, triggerConnectedAccountMatches, confirmConnectedAccountMatches, getOauthConnectUrl, oauthDisconnect, connectListing, disconnectListing, createGmbListingGoogle 和 Facebook 的 OAuth 連線、商家資訊連結
fetchPlanSites, fetchCountries, fetchSubscriptions, fetchSubcategories方案目錄、支援的國家、訂閱、商家類別

此 SDK 尚未封裝 Social API，涵蓋品牌、已連結的社群帳號，以及發布至 Facebook、Instagram、X、LinkedIn 和 Pinterest 的貼文；請依照 Social REST 參考文件直接呼叫。

分頁

傳回清單的方法支援游標式分頁。

TypeScript
// 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 會原樣接受，編碼器也已匯出，供您需要時自行使用。

TypeScript
import { encodeLocationId } from 'listingsapi-js'; // These are equivalentawait client.fetchPremiumListings(16808);await client.fetchPremiumListings('TG9jYXRpb246MTY4MDg='); encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='

錯誤處理

所有 SDK 錯誤都衍生自 ListingsAPIError。API 發生錯誤時會擲回 APIError 或其子類別，無論平台是透過 HTTP 狀態還是 HTTP 200 回應主體回報錯誤（無效權杖及寫入驗證錯誤會以 errors[] 酬載傳回，寫入也可能回報 success: false）。SDK 會針對上述所有情況擲回錯誤，因此您無須自行檢查 success 旗標。網路連線失敗時會擲回 APIConnectionError。

類別擲回時機
AuthenticationError401，或無效權杖錯誤酬載
PermissionDeniedError403，或權限錯誤酬載
NotFoundError404
ValidationError400/422，或寫入傳回 success: false / errors[]
RateLimitError429，包含以秒為單位的 retryAfter
InternalServerError5xx
APIConnectionError網路連線失敗，請求未送達 API

每個 APIError 都包含 statusCode、responseBody、code（第一個平台錯誤代碼，e.g。"SY10005"），以及 errors（每個項目都正規化為 { code, message, context }）。

TypeScript
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）。重試模式與狀態碼說明請參閱錯誤處理。

後續步驟