실물 가격 시계열 API

미국 주간 연료 소매 가격, 일별 석유·가스 현물 가격, 월간 원자재 기준 가격을 검색하세요.

엔드포인트 및 요청

REST 엔드포인트

GET /v1/commodities/physical/series

계약 요청

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series?commodity=gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 사용 항목 commodities_list_physical_series. REST와 MCP는 동일한 스키마, 계정 할당량, 권한 확인 및 문제 형식을 공유합니다.

매개변수

이름	필수	유형	의미
`commodity`	아니요	쿼리 · 문자열	gasoline, diesel, copper, urea, rice, crude-oil, coffee 등의 원자재로 필터링합니다. 검색에서 반환된 commodity 값을 사용하세요.
`category`	아니요	쿼리 · 범주	제공 범주는 softs, oils-oilseeds, metals, grains, energy, fertilizers, forestry, livestock-dairy입니다. 연료 시계열은 energy를 사용합니다.
`country`	아니요	쿼리 · 국가 코드	세계 기준 가격에는 WLD, 유럽연합에는 EUU를 사용하세요. 제공 국가 코드는 USA, THA, JPN, AUS, ZAF, MYS, CMR, VNM, MEX, LKA, IND, KEN입니다. 미국 연료는 USA를 사용합니다.
`price_type`	아니요	쿼리 · 가격 유형	연료는 retail_average를 사용합니다. EIA 일간 현물과 World Bank 시계열은 international_benchmark를 사용하지만, 담배는 import_unit_value를 사용합니다.
`currency`	아니요	쿼리 · 통화 코드	호가 통화로 필터링합니다. 두 출처 모두 현재 USD를 사용합니다.
`limit`	아니요	쿼리 · 정수, 1~500	페이지당 최대 항목 수입니다. 기본값은 100입니다.
`cursor`	아니요	쿼리 · 문자열	이전 페이지의 next_cursor를 동일한 필터 및 limit과 함께 사용하세요. null은 더 이상 페이지가 없음을 뜻합니다.

출처: 미국 에너지정보청. 출처: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

응답

계약 예시

{
  "series": [
    {
      "series_id": "fuel-eia-usa-regular-gasoline",
      "commodity": "gasoline",
      "category": "energy",
      "product": "regular-gasoline",
      "country": "USA",
      "price_type": "retail_average",
      "basis": "cash self-serve pump price incl. all taxes, 8:00 a.m. Monday",
      "currency": "USD",
      "unit": "us_gallon",
      "unit_quantity": "1",
      "frequency": "weekly",
      "description": "United States: regular gasoline (all formulations), weekly average retail price in dollars per gallon from EIA's Monday survey (series EMM_EPMR_PTE_NUS_DPG.W).",
      "attribution": "Source: U.S. Energy Information Administration",
      "coverage_start": "1990-08-20",
      "coverage_end": "2026-10-19"
    }
  ],
  "next_cursor": null
}

필드	유형	필수	의미
`series`	배열	예	commodity, product, country, area, 가격 기준 basis, currency, unit, frequency, attribution 및 제공 기간을 포함하는 시계열입니다. 빈 배열은 일치하는 시계열이 없음을 뜻합니다.
`series[].series_id`	문자열	예	시계열 검색에서 반환되는 고정 ID입니다.
`series[].currency`	문자열	예	호가 통화입니다. 미국 연료 및 월간 기준 가격 시계열 모두 USD를 사용합니다.
`series[].unit / series[].unit_quantity`	문자열	예	발표된 단위와 가격의 기준 수량입니다. 연료는 us_gallon을 사용합니다. 월간 기준 가격은 metric_ton, kilogram, barrel, cubic_meter, troy_ounce, mmbtu, dry_metric_ton_unit 또는 sheet를 사용합니다. 수량은 1이며, 합판만 100장당 USD를 사용합니다. 값은 환산하지 않습니다.
`series[].attribution`	문자열	예	데이터와 함께 응답의 출처 표시를 유지하세요. 출처: 미국 에너지정보청. 출처: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
`series[].commodity / series[].category / series[].product`	문자열	예	원자재, 범주 및 제품 정의입니다. 예: gasoline / energy / regular-gasoline, copper / metals / copper. 검색 시 각 시계열의 값을 반환합니다.
`series[].area`	문자열	아니요	area는 지역 범위를 나타내며 전국 시계열에서는 생략됩니다.
`series[].country`	문자열	예	WLD는 세계 벤치마크를 뜻합니다. EUU는 유럽연합을 뜻합니다. 국가에는 ISO alpha-3 코드를 사용합니다. 미국 연료의 전국 평균에는 USA를 사용합니다.
`series[].price_type`	문자열	예	연료는 retail_average를 사용합니다. EIA 일간 현물과 월간 시계열은 international_benchmark를 사용하지만, 담배는 import_unit_value를 사용합니다.
`series[].basis`	문자열	아니요	basis는 가격 정의를 설명하며 출처가 제공하지 않으면 생략됩니다.
`series[].frequency`	문자열	예	EIA 석유·가스 현물 가격은 일간, 미국 연료는 주간, World Bank 기준 가격은 월간입니다.
`series[].description`	문자열	예	시계열 정의입니다.
`series[].coverage_start / series[].coverage_end`	날짜	예	가장 이른 관측값의 첫날과 가장 최근 관측값의 마지막 날이며 두 날짜를 모두 포함합니다. 일부 시계열은 늦게 시작하거나 종료되었습니다. 날짜 범위가 공백 없는 이력을 보장하지는 않습니다.
`next_cursor`	문자열 또는 null	예	내부 구조를 해석할 필요 없이 사용하는 연속 조회 토큰입니다. null은 마지막 페이지를 나타냅니다.

오류 및 할당량

400 invalid_query, 코드, 지역, 날짜 범위, limit 또는 선택자가 유효하지 않습니다.
400 invalid_cursor, 커서가 유효하지 않거나 요청 필터와 일치하지 않습니다.
401 invalid_api_key, Bearer 키가 없거나 거부되었습니다.
409 cursor_expired, 발표 자료가 변경되었습니다. 커서 없이 페이지 조회를 다시 시작하세요.
429 rate_limit_exceeded 또는 quota_exhausted, 공통 사용 한도를 모두 소진했습니다.
503 physical_reference_unavailable, 완전한 발표 자료를 사용할 수 없습니다.

거부된 요청과 서버 오류는 월간 할당량을 소비하지 않습니다.

데이터 범위

미국 주간 소매 연료 시계열 20개입니다. 일반 휘발유와 도로용 No. 2 디젤에 대해 각각 미국 평균과 9개 지역을 제공합니다. 가격 단위는 미국 갤런당 USD입니다. 미국 평균 이력은 휘발유가 1990년 8월, 디젤이 1994년 3월에 시작합니다. 지역별 시계열은 더 늦게 시작합니다. 매주 월요일 조사 후 이력이 추가됩니다. 출처: U.S. Energy Information Administration. EIA의 일간 현물 시계열 3개는 쿠싱 WTI 원유, 브렌트 원유, 헨리허브 천연가스를 다루며, 단위는 배럴당 USD 또는 백만 Btu당 USD입니다. 월간 데이터에는 World Bank 시계열 70개가 포함되며, 연성 원자재, 유지 및 유지종자, 금속, 곡물, 에너지, 비료, 임산물, 축산 및 유제품을 다룹니다. 이력은 1960년까지 거슬러 올라가지만 일부 시계열은 더 늦게 시작합니다. 매월 발표 후 새 월이 추가되지만 개별 시계열은 지연되거나 종료되었을 수 있습니다. 보리와 수수는 2020년 8월에, 멕시코 새우는 2023년 10월에 종료됩니다. 각 시계열의 coverage_end를 확인하세요. 모든 가격은 USD와 공표된 단위를 사용합니다. 출처: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

Narwhal API 키로 사용할 수 있습니다.