任意系列APIリファレンス

世界銀行とカナダ統計局のカタログを検索し、IDで系列を取得します。プランの上限、キャッシュ、エラー処理についても説明します。

4つの操作で、世界銀行とカナダ統計局の系列にIDでアクセスできます。カタログの検索、系列の定義や観測値の取得、最大50系列の最新値の一括取得ができます。

RESTとMCPは、スキーマ、キー、クォータを共有します。IDで取得する世界銀行とカナダ統計局のライブ系列には、改定履歴がありません。Proキーでは、対応する国別の履歴ルートとIDで系列を取得するルートで、過去の公表時点のデータを取得できます。詳しくは、経済指標APIリファレンスの「IDによる系列履歴」を参照してください。

操作一覧

操作	REST パス	MCPツール	戻り値
カタログを検索	`GET /v1/economics/catalogue`	`economics_search_catalogue`	クエリに一致する系列と表です。
系列を取得	`GET /v1/economics/catalogue/series`	`economics_read_catalogue_series`	1つの系列の定義です。
観測値を取得	`GET /v1/economics/catalogue/series/observations`	`economics_read_catalogue_observations`	1つの系列の値を古い順に返します。
最新値	`GET /v1/economics/catalogue/latest`	`economics_read_catalogue_latest_batch`	1〜50系列それぞれの最新値です。

データソースのキーにはスラッシュが含まれることがあるため、系列IDはidクエリパラメーターで渡してください。

すべてのリクエストにBearerキーが必要です。認証

系列ID

系列IDは小文字の<source>:<key>形式です。

出典	形式	例	頻度
世界銀行、世界開発指標	`wdi:<indicator>/<iso3>`	`wdi:ny.gdp.mktp.cd/idn`	年次
カナダ統計局	`statcan:v<vector>`	`statcan:v41690973`	月次、四半期、年次

世界銀行の検索結果には、wdi:ny.gdp.mktp.cd/{country}などのid_templateが含まれます。{country}を小文字のISO 3166-1 alpha-3国コードに置き換えてください。インデックスに含まれるのはCC BY 4.0で公開された指標のみです。それ以外の指標は404 not_foundを返します。

カナダ統計局の検索結果は表を示します。各結果には、id_templateとしてstatcan:v{vector}と、表10-10-0106-01のように表番号を含むタイトルがあります。カナダ統計局の該当する表のウェブページで系列のベクトル番号を確認し、テンプレートに挿入してください。現在、表のベクトル一覧を取得するルートはありません。

カナダ統計局のベクトルのうち、頻度が日次、週次、複数年、会計年度、会計四半期のものは404 not_foundを返します。

カタログを検索

検索ではデータソースを呼び出さず、Narwhalのインデックスを使います。すべてのプランで利用でき、1回の呼び出しとしてカウントされます。

q：検索文字列、2〜100文字です。
source：wdiまたはstatcanです。
country：大文字のISO alpha-3コードです。
frequency：daily、monthly、quarterly、annualのいずれかです。
limit：1〜100、デフォルトは25です。
cursor：前のページのnext_cursorです。

各結果にはsource、titleと、idまたはid_templateのどちらか一方が含まれます。判明している場合は、frequency、unit_label、country、first_period、last_periodも含まれます。最終ページのnext_cursorはnullです。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "results": [
    {
      "id_template": "wdi:bg.gsr.nfsv.gd.zs/{country}",
      "source": "wdi",
      "title": "Trade in services (% of GDP)",
      "frequency": "annual",
      "unit_label": "Trade in services (% of GDP)"
    },
    {
      "id_template": "wdi:bm.klt.dinv.wd.gd.zs/{country}",
      "source": "wdi",
      "title": "Foreign direct investment, net outflows (% of GDP)",
      "frequency": "annual",
      "unit_label": "Foreign direct investment, net outflows (% of GDP)"
    }
  ],
  "next_cursor": "eyJhIjoid2RpOmJtLmtsdC5kaW52LndkLmdkLnpzIiwicSI6IjBhOTNhNWZiMmE1NzkzY2EifQ"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=consumer%20price&source=statcan&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "results": [
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Consumer Price Index (CPI) statistics, alternative measures, unadjusted and seasonally adjusted, Bank of Canada (Statistics Canada table 10-10-0106-01)",
      "frequency": "monthly",
      "country": "CAN",
      "first_period": "1979-11",
      "last_period": "2026-09"
    },
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Inter-city indexes of price differentials of consumer goods and services, annual (Statistics Canada table 18-10-0003-01)",
      "frequency": "annual",
      "country": "CAN",
      "first_period": "2000",
      "last_period": "2019"
    }
  ],
  "next_cursor": "eyJhIjoic3RhdGNhbjp0MTgxMDAwMDMiLCJxIjoiNGQxYjFkOWQwN2FlNTBhMiJ9"
}

系列を取得

最初と最後の期間を含む、1つの系列の定義を返します。観測値は含まれません。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "title": "GDP (current US$), Indonesia",
  "country": "IDN",
  "frequency": "annual",
  "unit": "extended",
  "unit_label": "GDP (current US$)",
  "seasonal_adjustment": "not_stated",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "first_period": "1967",
  "last_period": "2025"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "first_period": "1914-01",
  "last_period": "2026-09"
}

観測値を取得

1つの系列の値を古い順に、系列の定義とともに返します。

id：系列IDです。
startとend：両端を含む範囲を、系列の期間形式であるYYYY、YYYY-MM、YYYY-Qnのいずれかで指定します。両端は同じ形式にする必要があります。
limit：1〜1000、デフォルトは100です。
cursor：前のページのnext_cursorです。

Narwhalはstartとendを適用した後に、プランの履歴範囲を適用します。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=wdi:ny.gdp.mktp.cd/idn&limit=3" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "title": "GDP (current US$), Indonesia",
  "country": "IDN",
  "frequency": "annual",
  "unit": "extended",
  "unit_label": "GDP (current US$)",
  "seasonal_adjustment": "not_stated",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "observations": [
    {
      "period": "1967",
      "value": "5667756627.92093"
    },
    {
      "period": "1968",
      "value": "7076465299.81141"
    },
    {
      "period": "1969",
      "value": "8337423312.88344"
    }
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=statcan:v41690973&start=2026-07&limit=3" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "observations": [
    {
      "period": "2026-07",
      "value": "169.9",
      "released_on": "2026-08-17"
    },
    {
      "period": "2026-08",
      "value": "169.8",
      "released_on": "2026-09-14"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19"
    }
  ],
  "next_cursor": null
}

データソースが値を公表していない年や月は省略され、補完されません。各観測値にはperiodと、小数を表す文字列のvalueが含まれます。データソースが提供する場合は、released_onとstatusも含まれます。

1回のリクエストで最新値を取得

重複しない1〜50個のIDを、カンマ区切りのidsリストで送信してください。レスポンスは各系列の最新の観測値と定義を返します。missingリストには、データソースが認識しないID、または観測値がないIDが含まれます。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "observations": [
    {
      "period": "2025",
      "value": "1445642584163.81",
      "id": "wdi:ny.gdp.mktp.cd/idn",
      "title": "GDP (current US$), Indonesia",
      "country": "IDN",
      "frequency": "annual",
      "unit": "extended",
      "unit_label": "GDP (current US$)",
      "seasonal_adjustment": "not_stated",
      "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
      "licence_url": "https://creativecommons.org/licenses/by/4.0/",
      "fetched_at": "2026-10-27T03:37:35Z"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19",
      "id": "statcan:v41690973",
      "title": "Canada;All-items",
      "frequency": "monthly",
      "unit": "extended",
      "unit_label": "2002=100",
      "seasonal_adjustment": "not_stated",
      "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
      "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
      "fetched_at": "2026-10-27T12:30:59Z"
    }
  ],
  "missing": []
}

バッチは、返された系列ごとに1回の呼び出しとしてまとめて利用枠から差し引かれます。

プランの上限

4つの操作はすべてのプランで利用できます。各プランには、キャッシュがない場合のデータソースからの1日あたりの取得回数と、履歴範囲の上限があります。

上限	無料	Basic	Pro
UTC日あたりのキャッシュなし取得回数	10	100	1,000
履歴範囲	過去12か月	過去5年	全期間の履歴

すべてのプランで、履歴範囲外であっても、年次系列は少なくとも最新5件、四半期系列は少なくとも最新4件の観測値を取得できます。Narwhalは、履歴範囲とこれらの最新の観測値のうち、より多くの観測値を含む方を採用します。

指定範囲全体がプランの履歴範囲より前の場合は、403 plan_upgrade_requiredを返します。年次系列と四半期系列では、最低観測値数を適用できるように、Narwhalはこの確認の前に系列を読み込みます。

データは遅延なしでライブ提供されます。

呼び出し回数、キャッシュ、古いデータ

検索、系列、観測値、単一系列の最新値のリクエストは、成功するたびに1回の呼び出しとしてカウントされます。バッチは、返された系列ごとに1回の呼び出しとしてカウントされます。

古いデータを返すレスポンスと、400、404、503のレスポンスは利用枠を消費しません。

Narwhalは、データソースから読み込んだ各系列をキャッシュします。キャッシュ済みの系列は、再取得せずに常にレスポンスを返します。取得回数を消費するのは、キャッシュがない系列のみです。世界銀行の系列は24時間〜7日間キャッシュされます。カナダ統計局のキャッシュ期間は、月次系列が6時間、四半期系列が12時間、年次系列が24時間です。

アカウントが1日の取得回数を使い切ると、追加の取得が必要なリクエストは429 fetch_limit_reachedを返します。Retry-Afterヘッダーには、00:00 UTCまでの残り時間が示されます。系列の古いコピーが残っている場合、Narwhalは利用枠を消費せずにstale: trueを付けて返します。

データソースが停止していて、キャッシュされたコピーもない場合、NarwhalはRetry-Afterを付けて503 upstream_busyを返します。データソースのレート制限を429レスポンスとしてそのまま返すことはありません。

フィールド

系列のレスポンスには、以下のフィールドが含まれます。

フィールド	意味
`id`	系列IDです。
`title`	データソースが提供する系列のタイトルです。
`country`	データソースが提供する場合のISO alpha-3コードです。
`frequency`	`daily`、`monthly`、`quarterly`、`annual`のいずれかです。
`unit`	常に`extended`です。
`unit_label`	データソースの表記による単位です。世界銀行の系列では、`GDP (current US$)`などの指標名を使います。
`scale, currency`	データソースに明記されている場合のみ含まれます。Narwhalが値に`scale`を適用することはありません。
`seasonal_adjustment`	`seasonally_adjusted`、`not_seasonally_adjusted`、`not_applicable`、`not_stated`のいずれかです。
`base_period`	データソースに明記されている場合の指数の基準です。
`attribution, licence_url`	必須の出典表示と、データソースのライセンスへのリンクです。
`fetched_at`	Narwhalがデータソースを読み込んだ時刻です。
`stale`	データソースに接続できず、Narwhalが最後に保存したコピーを返す場合のみ`true`です。
`first_period, last_period`	系列の定義に含まれる、最初と最後の期間です。

エラー

ステータスとコード	意味
`400 invalid_series_id`	IDのデータソース形式が無効です。詳細には、世界銀行の場合は`<indicator>/<iso3 country>`、カナダ統計局の場合は`v<vector number>`が示されます。
`400 invalid_query`	パラメーターが無効です。たとえば、バッチ内のIDが50個を超える場合、IDが重複する場合、`start`と`end`の期間形式が異なる場合が該当します。
`403 plan_upgrade_required`	指定範囲の終了時点が、プランの履歴範囲より前です。
`404 not_found`	データソースまたはインデックスが系列を認識しないか、系列の頻度がサポート対象外です。Narwhalはこの結果を24時間キャッシュします。
`404 not_covered`	IDがサポート対象外のデータソースを指定しています。
`429 fetch_limit_reached`	アカウントがUTC日あたりの取得枠を使い切っています。`Retry-After`には、00:00 UTCまでの残り時間が示されます。
`503 upstream_busy`	データソースを利用できず、キャッシュされたコピーもありません。`Retry-After`で指定された時間を待ってから再試行してください。

エラーは共通の問題形式に従い、request_idを含みます。エラーとクォータ

世界銀行データAPI · カナダ統計局データAPI

出典表示

各レスポンスはattributionに機関名、licence_urlにライセンスへのリンクを含みます。世界銀行の指標にはCC BY 4.0、カナダ統計局のデータにはカナダ政府オープンライセンスが適用されます。Narwhalは値を正規化します。値を表示するすべての場所で、出典表示を維持してください。

経済データAPIリファレンス · MCP