R で Narwhal の経済データを取得する

セットアップする内容

R は httr2 で Narwhal の REST API を呼び出し、JSON レスポンスを読めます。再利用できる narwhal() ヘルパー、6つのデータ領域すべての呼び出し、pull.R としてスケジュールできるスクリプトが手に入ります。ヘルパーはベース URL に https://api.narwhalapi.com を使い、リクエストごとにパスとクエリパラメーターを追加します。Narwhal の経済データには CPI、インフレ率、GDP、利回りが含まれ、ここでの経済データの呼び出しは CPI の観測値を選びます。

例では、レスポンスの領域ごとに R のオブジェクトを分けています。祝日と公開日はレコードのリストで返り、CPI の観測値、為替レート、予測市場の会合も同様です。コモディティの例は、1つの price フィールドを読みます。計算用にフィールドを選ぶときやレコードをデータフレームにするときは、これらのレスポンスの形を意識してください。

APIキーを設定

1. 無料キーを作成する narwhalapi.com/signup でキーを作成してください。Narwhal は、データ API 全体で1つのアカウントと1つの API キーを使います。
2. キーを .Renviron に保存する キーは、環境変数名 NARWHAL_API_KEY で .Renviron に入れます。プレースホルダーをご自身のキーに置き換え、キーは pull.R に書かないでください。変数名は、ヘルパーの Sys.getenv() に渡す名前と一致させる必要があります。環境変数の例の ... が、キーを入れるプレースホルダーです。
   環境変数

   NARWHAL_API_KEY=...

3. R のパッケージをインストールする ここに示すコマンドで httr2 と jsonlite をインストールします。リクエストのヘルパーは、httr2 で GET リクエストを送り、JSON の本文を読みます。
   パッケージをインストールする

   install.packages(c("httr2", "jsonlite"))

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

このコードを pull.R に保存します。ヘルパーは Sys.getenv() で NARWHAL_API_KEY を読み、Authorization: Bearer YOUR_KEY ヘッダーでキーを Bearer トークンとして送ります。各呼び出しでパスを指定し、日付範囲や通貨の指定が必要な呼び出しでは、クエリパラメーターも指定します。以降の領域ごとのサンプルでも、同じヘルパーを使います。

library(httr2)

narwhal <- function(path, ...) {
  request("https://api.narwhalapi.com") |>
    req_url_path_append(path) |>
    req_url_query(...) |>
    req_auth_bearer_token(Sys.getenv("NARWHAL_API_KEY")) |>
    req_perform() |>
    resp_body_json()
}

holidays <- narwhal("v1/calendars/holidays/USA/2026")$holidays
releases <- narwhal("v1/economics/calendar", countries = "USA",
                    start_date = "2026-11-01", end_date = "2026-11-30",
                    limit = 100)$releases
cpi      <- narwhal("v1/economics/USA/cpi/observations", start = "2025-09")$observations
brent    <- as.numeric(narwhal("v1/commodities/spot/BRENT/USD")$price)
fx       <- narwhal("v1/fx/rates/USD", currencies = "EUR,IDR")$rates
fed      <- narwhal("v1/predictions/policy-paths/federal-reserve")$meetings

cpi_values <- vapply(cpi, function(row) as.numeric(row$value), numeric(1))
n <- length(cpi_values)
mom <- cpi_values[n] / cpi_values[n - 1] - 1
print(round(mom * 100, 2))   # month-on-month change in percent

ヘルパーの中では、req_url_path_append(path) がベース URL にエンドポイントのパスを追加し、req_url_query(...) がクエリ引数を追加します。req_auth_bearer_token() は、環境変数から読んだキーを受け取ります。そのあと呼び出しは req_perform() と resp_body_json() でレスポンスの本文を R に返します。各領域の例のように、その本文から $ で名前付きのフィールドを読みます。

CPI の計算では、各観測値の value を数値として読みます。返されたリストの最後の値を、その1つ前の値で割って1を引き、前月比の変化を割合(パーセント)で表示します。観測値の値を計算の外で使うときは、period フィールドを各観測値とあわせて保持してください。

レコードのリストをデータフレームにするには、dplyr::bind_rows か do.call(rbind, lapply(x, as.data.frame)) を使います。ここで x は、holidays、releases、cpi など、変換したいリストです。変換にその領域のレコードが渡るように、先にレスポンスのフィールドを選んでください。

これらの呼び出しでは、パスとクエリ引数を分けています。CPI では、パスで USA の CPI 観測値を選び、start で開始期間を指定します。為替では、パスで USD を選び、currencies で EUR と IDR を指定します。どちらの呼び出しも、ヘルパーのベース URL と Bearer 認証を使います。

毎日の取得をスケジュールする

cron か Windows Task Scheduler で、Rscript pull.R を1日1回実行するようにスケジュールします。cronR パッケージで cron の行を書くこともできます。必要なリクエストは、ヘルパーと環境変数の参照とともに pull.R に入れておき、スケジュールしたコマンドが同じスクリプトを呼び出すようにします。

Rscript pull.R

日付と通貨の指定は、スクリプトに書いたままです。たとえば、公開日の呼び出しは2026年11月を、祝日の呼び出しは2026年の USA の祝日を指定しています。毎日のスケジュールでは、これらのリクエストが繰り返されます。スケジュールの手順は 毎日のデータ取得をスケジュールする を参照してください。

R の祝日

holidays から、2026年の USA の祝日を読みます。各レコードに date と name があるので、レコードをデータフレームにするときは両方のフィールドを残してください。この呼び出しはパスに国と年を使い、レスポンスから祝日のリストを読みます。

response <- narwhal("v1/calendars/holidays/USA/2026")
holidays <- response$holidays
holidays

R の公開日

releases から、2026年11月の USA の経済指標の公開日を読みます。リクエストには、国、開始日、終了日、上限が含まれます。各公開に at、period、topic、status があるので、R で公開のレコードを使うときは、これらのフィールドをまとめて保持してください。

response <- narwhal("v1/economics/calendar", countries = "USA",
                    start_date = "2026-11-01", end_date = "2026-11-30", limit = 100)
releases <- response$releases
releases

R の経済データ

observations から、2025年9月を開始期間とする USA の CPI 観測値を読みます。各観測値に period と value があります。ヘルパーの例は、これらの値で前月比を計算します。観測値や、そこから得た結果を示すときは、期間を値と並べて保持してください。

response <- narwhal("v1/economics/USA/cpi/observations", start = "2025-09")
cpi <- response$observations
cpi

R のコモディティのスポット価格

price から、USD での Brent のスポット価格を読みます。この呼び出しは、パスでコモディティと通貨を選び、返された価格を as.numeric() で変換します。コモディティのスポットコードには、たとえば XAU、XAG、XPT、XPD、XCU、BRENT、WTI があります。

response <- narwhal("v1/commodities/spot/BRENT/USD")
brent <- as.numeric(response$price)
brent

R の為替レート

USD を基準通貨にして、リクエストした通貨 EUR と IDR の為替レートを読みます。レスポンスのフィールドは rates で、各レコードに currency と rate があります。リストをデータフレームに変換するときは、通貨フィールドをそのレートと一緒に保持してください。

response <- narwhal("v1/fx/rates/USD", currencies = "EUR,IDR")
fx <- response$rates
fx

R の予測市場のオッズ

meetings から、Federal Reserve の政策金利パスのレスポンスを読みます。各会合に resolves_at、p_cut、p_hold、p_hike があります。確率を R に読み込むときは、会合のフィールドをまとめて保持し、利下げ、据え置き、利上げのフィールドと並べて決着時刻も残してください。

response <- narwhal("v1/predictions/policy-paths/federal-reserve")
fed <- response$meetings
fed

キーはどこに置きますか。

キーは .Renviron に入れ、スクリプトには書かないでください。ヘルパーは Bearer 認証のために Sys.getenv("NARWHAL_API_KEY") を読みます。REST と MCP でキーを共有するので、どちらの方法で Narwhal を使っても、同じアカウントとキーを使います。

price が文字列なのはなぜですか。

10進数は文字列で返されます。R の計算で使うには、Brent の例のように as.numeric() で price を数値に変換してください。CPI の計算でも、値を割って変化を求める前に、各観測値の value を変換しています。