세계은행 데이터 API

국가별 연간 지표 조회

아래 라이선스 제한에 따라 wdi:<indicator>/<iso3>로 특정 국가의 WDI 지표를 조회합니다. 두 부분 모두 소문자를 사용합니다. 국가 부분에는 인도네시아의 idn과 같은 ISO 3166-1 alpha-3 코드를 사용합니다.

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,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 매개변수에 서로 다른 시계열 ID를 1개부터 50개까지 쉼표로 구분해 전송하면 최신 관측값을 조회할 수 있습니다. 여러 국가의 동일한 지표를 요청하려면 지표 부분을 유지하고 국가 코드를 바꿉니다.

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 기준 하루 단위로 적용됩니다. 시계열이 캐시에 없을 때만 원천 조회가 필요합니다. 일일 한도를 모두 사용한 후에도 캐시된 시계열은 계속 조회할 수 있습니다.

연간 데이터는 요금제의 조회 기간과 최신 관측값 5개 중 더 많은 관측값을 포함하는 범위까지 조회할 수 있습니다. 요청 범위 전체가 허용된 과거 데이터 범위보다 이전이면 403 plan_upgrade_required를 반환합니다.

한도를 모두 사용한 후 원천 조회가 필요한 요청은 429 fetch_limit_reached를 반환하며, Retry-After는 00:00 UTC까지의 대기 시간을 나타냅니다. 한도에 도달한 계정에 보관된 사본이 있으면 사용량 차감 없이 해당 사본을 반환합니다.

라이선스 및 출처 표시 보관

카탈로그에는 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일까지 캐시합니다. 캐시에 없으면 Narwhal은 요금제의 일일 한도 내에서 원천 데이터를 가져옵니다.

관측값의 period와 fetched_at을 구분하여 확인합니다. 전자는 측정 대상 연도를 나타내며, 후자는 데이터를 가져온 시점을 기록합니다. 원천에 연결할 수 없으면 보관된 사본을 stale: true와 함께 반환할 수 있습니다.