임의 시계열 API 레퍼런스

세계은행과 캐나다 통계청 카탈로그를 검색하고 ID로 시계열을 조회합니다. 요금제별 제한, 캐싱, 오류 처리도 설명합니다.

4가지 작업으로 ID를 사용해 세계은행과 캐나다 통계청의 시계열에 접근할 수 있습니다. 카탈로그를 검색하거나, 시계열 정의 또는 관측값을 조회하거나, 한 번에 최대 50개 시계열의 최신 값을 가져올 수 있습니다.

REST와 MCP는 스키마, 키, 할당량을 공유합니다. ID로 조회하는 세계은행 및 캐나다 통계청의 실시간 시계열에는 수정 이력이 없습니다. Pro 키는 Economics API 레퍼런스의 ID별 시계열 이력 항목에 설명된 대로, 지원되는 국가별 이력 및 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회로 최신 값 조회

서로 다른 ID 1~50개를 쉼표로 구분한 ids 목록으로 전송합니다. 응답은 각 시계열의 최신 관측값과 정의를 반환합니다. missing 목록에는 출처에서 인식하지 못하거나 관측값이 없는 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가지 작업 모두 모든 요금제에서 사용할 수 있습니다. 각 요금제에는 캐시가 없는 원본 데이터 조회의 일일 한도와 이력 조회 기간이 정해져 있습니다.

한도	무료	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시간입니다.

계정의 일일 원본 데이터 조회 한도를 모두 사용한 뒤 추가 조회가 필요한 요청은 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