Listings APIListings API
登入

設定

設定 listingsapi-js 用戶端：API 金鑰解析、基底 URL 覆寫、逾時與自動重試。

建構函式選項

ListingsAPI 接受單一選項物件；物件本身及其中所有選項皆可省略：

選項型別必填預設值說明
apiKeystring否process.env.LISTINGSAPI_KEY您的 Listings API 金鑰。若省略，用戶端會讀取 LISTINGSAPI_KEY 環境變數；若兩者皆未設定，則拋出 AuthenticationError。
baseUrlstring否https://listingsapi.com覆寫 API 主機，適用於代理伺服器或預備環境。結尾的斜線會自動移除。
timeoutnumber否240000每個請求的逾時時間，以毫秒為單位，透過 AbortSignal.timeout 強制執行。
maxRetriesnumber否2遇到速率限制、伺服器錯誤及網路故障時，自動重試。僅適用於讀取操作；寫入操作一律不會重試。設為 0 即可停用。
TypeScript
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from env // Every default spelled out:const custom = new ListingsAPI({apiKey: process.env.LISTINGSAPI_KEY,baseUrl: 'https://listingsapi.com',timeout: 240000,   // 4 minutes per attemptmaxRetries: 2,     // up to 3 attempts total});

API 金鑰的取得方式

請勿將金鑰寫死在原始碼中。無引數的建構函式會從環境讀取 LISTINGSAPI_KEY：

Shell
export LISTINGSAPI_KEY="your-api-key"
TypeScript
const client = new ListingsAPI();

或傳入您從機密管理服務取得的金鑰：

TypeScript
import { getSecret } from './secrets.js'; const apiKey = await getSecret('LISTINGSAPI_KEY');const client = new ListingsAPI({ apiKey });

若兩處皆找不到金鑰，建構函式會在發出任何請求之前，立即拋出 AuthenticationError。

覆寫基底 URL

將用戶端指向內部代理伺服器或預備環境：

TypeScript
const client = new ListingsAPI({baseUrl: 'https://listings-proxy.internal.example.com',});

結尾的斜線會自動移除，因此 'https://listingsapi.com/' 與 'https://listingsapi.com' 的行為相同。

逾時設定

內部會以 AbortSignal.timeout(timeout) 包裝每次嘗試（Node 18+），因此您不必自行在 SDK 呼叫外加上 AbortController。預設為每次嘗試 240000 毫秒（4 分鐘）。

嘗試逾時會視為連線失敗：只要還有剩餘的嘗試次數，用戶端就會重試，最後一次失敗時則會拋出 APIConnectionError。對於延遲敏感的程式執行路徑，請縮短逾時時間：

TypeScript
const client = new ListingsAPI({ timeout: 15000 }); // 15 s per attempt

自動重試

用戶端僅會針對安全方法 GET、HEAD 及 OPTIONS，在收到狀態為 429、500、502、503 及 504 的回應，或發生網路層級故障（DNS 錯誤、連線遭拒、逾時）時重試。自 0.3.2 起，寫入操作（POST、DELETE）只會傳送一次，失敗時會立即回報。使用預設的 maxRetries: 2 時，每次讀取最多嘗試 3 次。

v4 API 不支援 Idempotency-Key，也不會偵測重複寫入，因此逾時或傳回 5xx 的寫入操作可能已經提交。未經確認就重試，會建立第 2 個地點、貼文或評論回覆。在重複執行寫入操作之前，請先使用您掌控的索引鍵讀回該筆記錄。

每次重試前的等待時間：

  1. 若回應包含 Retry-After 標頭，且其值為正數秒數，用戶端就會依該秒數等待。
  2. 否則，等待時間會以指數方式增加：第 1 次重試前等待 500 毫秒，之後每次重試的等待時間加倍（1 秒、2 秒，依此類推）。

發生網路故障時會立即重試，不會等待。嘗試次數用盡後，最後一次回應會轉為具型別的錯誤（RateLimitError、InternalServerError 等；請參閱錯誤處理），而網路故障在嘗試次數用盡後會拋出 APIConnectionError。

TypeScript
// Fail fast and own the retry policy yourself:const client = new ListingsAPI({ maxRetries: 0 });

地點 ID

SDK 中所有接受地點 ID 的地方，都會自動將數值 ID 編碼為 API 的 base64 格式（Location:<id>），已編碼的 ID 則會原樣傳遞。SDK 也匯出了此輔助函式，供您自行取得編碼後的格式：

TypeScript
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808);                  // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // returned as-is

標頭格式

每個請求皆使用下列格式進行驗證：

Code
Authorization: API <your-key>Content-Type: application/json

SDK 會在每次呼叫時自動設定這些標頭。您不必自行設定。

TypeScript 專案設定

SDK 以 TypeScript 為主要設計語言，並內含型別定義，因此不必另外安裝 @types 套件。請固定版本，以確保建置結果可重現：

Shell
npm install listingsapi-js@0.3.2

Node 18+ 專案的最小 tsconfig.json 設定：

tsconfig.json
{"compilerOptions": {  "target": "ES2022",  "module": "Node16",  "moduleResolution": "Node16",  "strict": true,  "outDir": "dist"}}

若 ESM 專案的 package.json 中設有 "type": "module"，請使用 "module": "Node16" 與 "moduleResolution": "Node16"。對於 CJS 專案，使用 "module": "CommonJS" 與 "moduleResolution": "Node" 即可；套件包含這兩種建置版本，CommonJS 程式碼可透過 const { ListingsAPI } = require('listingsapi-js') 載入。

不使用 TypeScript

listingsapi-js 會編譯為純 JavaScript，沒有任何執行階段相依套件。您可以直接在 .js 或 .mjs 檔案中匯入，無須建置：

script.mjs
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI();const page = await client.fetchAllLocations({ first: 5 });for (const location of page.locations) {console.log(location.name, location.city); // Acme Dental Midtown}

後續步驟