Node SDK
Listings APIの公式TypeScriptクライアントです。Node 18以降に対応し、依存関係がなく、自動ページネーションと型定義を備えています。
listingsapi-jsは、Listings API v4の公式Node.js/TypeScriptクライアントです。階層のない単一のクライアントで、拠点、ディレクトリの掲載情報、レビュー、投稿、写真、プロフィールの分析データを管理でき、カーソルベースのページネーション、IDの自動エンコード、組み込みのリトライ処理、型付きエラーを標準で備えています。
インストール
npm install listingsapi-js認証
Listings API開発者ダッシュボードのAPI Keys → New keyからAPIキーを取得します。
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 ms）、maxRetries（デフォルトは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);}}リソース
すべてのメソッドはクライアントインスタンスにあります。
ブランド、接続済みのソーシャルアカウント、Facebook、Instagram、X、LinkedIn、Pinterestへの投稿を扱うSocial APIは、このSDKではまだラップされていないため、Social RESTリファレンスに従って直接呼び出してください。
ページネーション
一覧を返すメソッドは、カーソルベースのページネーションをサポートしています。
// 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はそのまま受け付けられ、エンコーダーもエクスポートされているため、必要に応じて直接使用できます。
import { encodeLocationId } from 'listingsapi-js'; // These are equivalentawait client.fetchPremiumListings(16808);await client.fetchPremiumListings('TG9jYXRpb246MTY4MDg='); encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='エラー処理
SDKのすべてのエラーはListingsAPIErrorから派生しています。APIの失敗時には、プラットフォームがHTTPステータスで報告する場合でも、HTTP 200のレスポンスボディ内で報告する場合でも、APIErrorまたはそのサブクラスがスローされます（無効なトークンと書き込み時の検証エラーはerrors[]ペイロードで返され、書き込みではsuccess: falseが報告されることもあります）。SDKはこれらすべてに対して例外をスローするため、successフラグを自分で確認する必要はありません。ネットワーク障害時にはAPIConnectionErrorがスローされます。
すべてのAPIErrorは、statusCode、responseBody、code（プラットフォームの最初のエラーコード、e.g. "SY10005"）、errors（各エントリは{ code, message, context }に正規化されます）を含みます。
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に従います）。リトライの実装パターンとステータスコードの扱いについては、エラー処理を参照してください。