世界銀行データAPI

国別の年次指標を取得する

以下のライセンス制限に従い、wdi:<indicator>/<iso3>で国別のWDI指標を取得します。両方の部分に小文字を使用します。国の部分にはISO 3166-1 alpha-3コードを使用し、インドネシアの場合はidnです。

WDI系列は年次データです。レスポンスは指標の単位ラベルを保持し、観測値は小数文字列で返します。欠けている年は省略し、補完しません。系列には改訂履歴や過去の公表時点別データはありません。

指標を検索する

qでカタログを検索し、source=wdiで結果を絞り込みます。検索はすべてのプランで利用でき、ソースへのリクエストは行いません。検索語は2から100文字で指定できます。limitは1から100件まで指定でき、デフォルトは25です。

curl "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  -H "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"
}

結果のid_template内の{country}を国コードに置き換えてください。対応するMCPツールはeconomics_search_catalogueです。

系列を取得する

idクエリパラメータに、スラッシュを含む完全なIDを指定します。まず定義を取得して、タイトル、頻度、単位ラベルを確認してください。インドネシアのGDPでは、ソースの単位ラベルはGDP (current US$)です。

curl "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  -H "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",
  "first_period": "1967",
  "last_period": "2025"
}

観測値は別途取得します。年次のstartとendにはYYYYを使用し、両方の年を含みます。観測値は1ページあたり最大1,000件取得できます。MCPでは、定義にeconomics_read_catalogue_series、値にeconomics_read_catalogue_observationsを使用します。

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

{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "observations": [
    {"period": "1967", "value": "5667756627.92093"},
    {"period": "1968", "value": "7076465299.81141"},
    {"period": "1969", "value": "8337423312.88344"}
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

複数の国のデータをまとめて取得する

idsパラメータに1から50個の重複しない系列IDをカンマ区切りで指定し、最新の観測値を取得します。指標の部分を固定して国コードを変更すると、複数の国の同じ指標を取得できます。

curl "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,wdi:ny.gdp.mktp.cd/jpn" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

返された系列ごとに1回の呼び出しとして数えられ、バッチは一括で計上されます。値を比較する際は、各観測値のperiodを確認してください。MCPツールはeconomics_read_catalogue_latest_batchです。

プラン別の制限を確認する

キャッシュ未格納データの取得枠は、アカウントごとにUTCの日単位で適用されます。ソースからの取得が必要なのは、系列がキャッシュにない場合だけです。1日の取得枠を使い切った後も、キャッシュ済みの系列は引き続き取得できます。

年次データでは、プランの履歴期間と最新5件の観測値のうち、より多くの観測値を含む方にアクセスできます。指定範囲全体が許可された履歴より前の場合は、403 plan_upgrade_requiredを返します。

取得枠を使い切った後にソースからの取得が必要になるリクエストは、429 fetch_limit_reachedと、UTCの00:00までの待機時間を示すRetry-Afterを返します。上限に達したアカウントでも保存済みのコピーがあれば、利用回数に計上せずにそのコピーを返します。

ライセンスと出典情報を保持する

カタログには、CC BY 4.0が適用される世界銀行のWDI指標が1,489件登録されています。別のライセンスが適用される9件の指標は、IDによるリクエストを拒否し、提供しません。

すべての系列レスポンスにattributionとlicence_urlが含まれます。使用するデータとともに、世界銀行の出典情報とCC BY 4.0ライセンスを保持してください。レスポンスにはfetched_atも含まれるため、観測期間と併せてNarwhalが系列を取得した日時を記録できます。

国コードを指定して世界銀行の指標を取得するにはどうすればよいですか？

指標を検索してid_templateを取得し、{country}を小文字のISO 3166-1 alpha-3コードに置き換えます。たとえば、インドネシアのGDP系列はwdi:ny.gdp.mktp.cd/idnです。

定義や観測値を取得する際は、その完全なIDをidパラメータに指定します。系列を保存したり比較したりする際も、国コードを指標に付けたままにしてください。

世界銀行のデータはどの時点のものですか？

WDIの観測値は年次データで、Narwhalは系列を24時間から7日間キャッシュします。キャッシュにない場合は、プランの1日の取得枠内でソースから取得します。

観測値のperiodとfetched_atは個別に確認してください。前者は測定対象の年を示し、後者は取得日時を記録します。ソースに接続できない場合、保存済みのコピーをstale: true付きで返すことがあります。