Listings APIListings API
サインイン

設定

listingsapi-jsクライアントのAPIキーの解決方法、ベースURLの上書き、タイムアウト、自動再試行を設定します。

コンストラクターのオプション

ListingsAPI は、すべての項目が省略可能なオプションオブジェクトを1つ受け取ります。オブジェクト自体も省略できます。

オプション型必須デフォルト説明
apiKeystringいいえprocess.env.LISTINGSAPI_KEYListings API のキーです。省略すると、クライアントは環境変数 LISTINGSAPI_KEY を読み取り、どちらにもキーが設定されていなければ AuthenticationError をスローします。
baseUrlstringいいえhttps://listingsapi.comAPI ホストを上書きします。プロキシやステージング環境を使用する場合に便利です。末尾のスラッシュは自動的に削除されます。
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 ms（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）は必ず1回だけ送信され、失敗した場合は直ちに呼び出し元に通知されます。デフォルトの maxRetries: 2 では、各読み取りを最大3回試行します。

v4 API は Idempotency-Key をサポートしておらず、書き込みの重複も検出しないため、タイムアウトした書き込みや 5xx が返された書き込みでも、すでにコミットされている可能性があります。確認せずに再試行すると、拠点、投稿、またはレビューへの返信が重複して作成されます。書き込みを繰り返す前に、自分で管理しているキーを使ってレコードを読み取り、確認してください。

各再試行までの待機時間は次のとおりです。

  1. レスポンスに正の秒数を指定した Retry-After ヘッダーが含まれている場合、クライアントはその秒数だけ待機します。
  2. それ以外の場合は、指数関数的に待機時間を延ばします。最初の再試行まで 500 ms 待機し、以降は再試行のたびに待機時間を2倍にします（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 はそのまま渡されます。エンコードされた形式が必要な場合に利用できるよう、ヘルパーがエクスポートされています。

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"}}

package.json に "type": "module" を指定した ESM プロジェクトでは、"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}

次の手順