Node.js API 取得：TypeScript で Narwhal API を使う

セットアップする内容

Node.js は、Narwhal REST API を呼び出して JSON のレスポンスを読み取るスクリプトの JavaScript 実行環境です。共通のリクエストヘルパーと、6つのデータ分野すべての呼び出しを備えた ES モジュールができあがります。Narwhal は1つのアカウントと1つの APIキーでデータ API 全体を利用でき、REST と MCP でも同じキーを共有します。ここでのスクリプトは REST を使い、キーは環境変数から読み取ります。

APIキーを設定

1. 無料キーを作成する 新規登録 で無料の APIキーを取得します。このスクリプトのどのデータ分野のリクエストも、同じキーで認証されます。
2. キーを環境ファイルに保存する キーを .env ファイルに NARWHAL_API_KEY という名前で記述します。YOUR_KEY を自分のキーに置き換えてください。スクリプトはその値を process.env.NARWHAL_API_KEY から読み取ります。
   環境ファイル

   NARWHAL_API_KEY=YOUR_KEY

3. ES モジュールと対応する Node のバージョンを使う スクリプトは pull.mjs として保存します。Node 18.17 以降にはグローバルな fetch があるため、REST 呼び出しにパッケージは不要です。node --env-file=.env pull.mjs で .env ファイルを読み込むには、Node 20.6 以降が必要です。

リクエストヘッダーは Authorization: Bearer YOUR_KEY です。スクリプトでは、ヘッダーの値を環境変数から取得し、ベース URL は https://api.narwhalapi.com のままです。どの呼び出しも、共通のヘルパーを通して同じヘッダーを使います。

コードでデータを取得する

このコードを pull.mjs に保存します。get ヘルパーは、ベース URL とパスから URL を組み立て、渡されたクエリパラメーターを追加して、fetch で GET リクエストを送ります。レスポンスが成功でなければ、ステータスとレスポンスのテキストを含むエラーを投げます。成功なら、呼び出し側のコードが読み取れるよう JSON のレスポンスを返します。

ヘルパーと各分野の呼び出しは同じ ES モジュールにまとめ、ベース URL とヘッダーはリクエストより前に定義します。パラメーターのオブジェクトは各呼び出しに属します。カレンダーの呼び出しは国と日付のフィルターを、CPI の呼び出しは開始期間を、FX の呼び出しは通貨を渡します。

const API = "https://api.narwhalapi.com";
const headers = { Authorization: `Bearer ${process.env.NARWHAL_API_KEY}` };

async function get(path, params = {}) {
  const url = new URL(API + path);
  for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

const { holidays } = await get("/v1/calendars/holidays/USA/2026");
const { releases } = await get("/v1/economics/calendar", {
  countries: "USA",
  start_date: "2026-11-01",
  end_date: "2026-11-30",
  limit: 100,
});
const { observations } = await get("/v1/economics/USA/cpi/observations", {
  start: "2025-09",
});
const { price } = await get("/v1/commodities/spot/BRENT/USD");
const { rates } = await get("/v1/fx/rates/USD", { currencies: "EUR,IDR" });
const { meetings } = await get("/v1/predictions/policy-paths/federal-reserve");

console.log(holidays.length, holidays[0].name);
console.log(releases.length, observations.at(-1));
console.log(
  "Brent",
  price,
  Object.fromEntries(rates.map((rate) => [rate.currency, rate.rate])),
);
console.log(meetings[0].resolves_at.slice(0, 10), meetings[0].p_hold);

node --env-file=.env pull.mjs を実行して、キーを読み込んで API を呼び出します。各呼び出しは、出力文で使うレスポンスのフィールドを取り出します。為替レートでは、返された通貨とレートの項目をスクリプトがオブジェクトに変換し、予測のレスポンスでは会合の日付とホールド確率を読み取ります。以下の各分野のサンプルでも、この同じ get ヘルパーとヘッダーを使います。

取得をスケジュールする

ホストの cron またはスケジュールジョブを使います。cron では、コマンドに環境ファイルのパスと pull.mjs のパスを含めるので、スケジュール実行されるスクリプトも process.env.NARWHAL_API_KEY でキーを使えます。コマンドをスケジュール実行する場合も、--env-file オプションには Node 20.6 以降が必要です。

0 7 * * * node --env-file=/path/.env /path/pull.mjs

/path/.env と /path/pull.mjs は、自分のファイルのパスに置き換えてください。リクエストのスケジュールの詳細は、毎日のデータ取得をスケジュールするを参照してください。

Node.js で祝日を扱う

2026年の米国の祝日をリクエストし、holidays 配列を読み取ります。各祝日には date と name があり、サンプルは配列の長さと最初の祝日名を表示します。2026年10月24日時点で、レスポンスには2026年の米国の祝日が11件含まれていました。自分の出力で日付を使うには、祝日の項目の date を読み取ります。name フィールドは、その日付に対応する祝日名を示します。

const { holidays } = await get(
  "/v1/calendars/holidays/USA/2026"
);
console.log(holidays.length, holidays[0].name);

Node.js で発表日を扱う

米国の経済カレンダーを2026年11月の期間でリクエストし、releases を読み取ります。各項目には at、period、topic、status があり、発表日をトピックや期間と並べて読み取れます。2026年10月24日時点で、この2026年11月の期間には31件の発表がありました。日付のフィルターはカレンダーのリクエストに属し、period フィールドは各発表の項目に属します。出力でトピックやステータスが必要なときは、同じ項目から読み取ってください。

const { releases } = await get("/v1/economics/calendar", {
  countries: "USA", start_date: "2026-11-01", end_date: "2026-11-30", limit: 100
});
console.log(releases.length);

Node.js で経済データを扱う

start パラメーターを付けて米国の CPI 観測値をリクエストし、observations を読み取ります。各観測値には period と value があり、サンプルは返された配列の最後の項目を読み取ります。2026年10月24日時点で、2026-09 の期間の CPI の値は 336.940 でした。Narwhal の経済データには、インフレ、GDP、利回りも含まれます。観測値を読み取るときは期間を値と一緒に保持し、出力でその値がどの CPI の期間に属するかが分かるようにします。リクエストの開始期間は、クエリパラメーターとして渡します。

const { observations } = await get(
  "/v1/economics/USA/cpi/observations", { start: "2025-09" }
);
console.log(observations.at(-1));

Node.js でコモディティのスポット価格を扱う

Brent を USD でリクエストし、レスポンスの price フィールドを読み取ります。2026年10月24日時点で、Brent は1バレル116.8809ドルでした。スポットコードには、たとえば XAU、XAG、XPT、XPD、XCU、BRENT、WTI があります。このサンプルでは、リクエストのパスに BRENT と USD を使っています。ここでのコードは、JSON レスポンスから単一の price フィールドを読み取ります。コモディティコードと通貨は、共通のリクエストヘルパーに渡す URL の一部です。

const { price } = await get(
  "/v1/commodities/spot/BRENT/USD"
);
console.log("Brent", price);

Node.js で為替レートを扱う

USD を基準に EUR と IDR をリクエストし、rates を読み取ります。各項目には currency と rate があり、小数のレートは文字列です。2026年10月24日時点で、USD/EUR は 0.89342、USD/IDR は 18107.8 でした。サンプルは、各通貨を返されたレートのオブジェクトのプロパティとして使います。リクエストする通貨はクエリパラメーターで、基準通貨はパスに含まれます。返された配列を直接使う場合は、各レートと一緒に通貨フィールドも読み取ってください。

const { rates } = await get(
  "/v1/fx/rates/USD", { currencies: "EUR,IDR" }
);
console.log(Object.fromEntries(rates.map((rate) => [rate.currency, rate.rate])));

Node.js で予測市場のオッズを扱う

連邦準備制度の政策パスをリクエストし、meetings を読み取ります。各会合には resolves_at、p_cut、p_hold、p_hike があります。2026年10月24日時点で、2026年10月28日の会合のホールド確率は 0.9188 でした。サンプルは、最初の会合の項目から日付をそのホールド確率と並べて表示します。利下げまたは利上げの確率が必要なときは、会合の項目の p_cut または p_hike を使います。確率がどの会合のものかが分かるよう、resolves_at を確率と一緒に保持してください。

const { meetings } = await get(
  "/v1/predictions/policy-paths/federal-reserve"
);
console.log(meetings[0].resolves_at.slice(0, 10), meetings[0].p_hold);

TypeScript の型は必要ですか?

読み取るレスポンスのフィールドだけに型を付けます。FX の例では、レスポンスの形は { rates: { currency: string; rate: string }[] } です。小数の値は文字列なので、TypeScript の型では rate に string を使います。

なぜ await がトップレベルにあるのですか?

ES モジュールではトップレベルの await が使えるため、サンプルは各 get 呼び出しをそのまま待機しています。ここで示した .mjs 拡張子を使うか、JavaScript の ES モジュールとして "type": "module" を設定してください。