실물 가격 시계열 상세 정보 API

주간 연료 또는 월간 기준 가격 시계열 하나의 정의, 단위, 제공 범위를 조회합니다.

엔드포인트 및 요청

REST 엔드포인트

GET /v1/commodities/physical/series/{series_id}

계약 요청

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/fuel-eia-usa-regular-gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

매개변수

이름	필수	유형	의미
`series_id`	예	경로 · 문자열	fuel-eia-usa-regular-gasoline 또는 worldbank-cmo-copper와 같이 검색에서 반환된 고정 ID를 사용하세요.

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

응답

계약 예시

{
  "series_id": "fuel-eia-usa-regular-gasoline",
  "commodity": "gasoline",
  "category": "energy",
  "product": "regular-gasoline",
  "market": "USA",
  "area": null,
  "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).",
  "publisher": "U.S. Energy Information Administration",
  "attribution": "Source: U.S. Energy Information Administration",
  "coverage_start": "2026-07-20",
  "coverage_end": "2026-10-05"
}

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

오류 및 할당량

400 invalid_query, 코드, 지역, 날짜 범위, limit 또는 선택자가 유효하지 않습니다.
401 invalid_api_key, Bearer 키가 없거나 거부되었습니다.
404 physical_series_not_found, 요청과 일치하는 완전한 승인 데이터가 없습니다.
429 rate_limit_exceeded 또는 quota_exhausted, 공통 사용 한도를 모두 소진했습니다.
503 physical_reference_unavailable, 완전한 발표 자료를 사용할 수 없습니다.

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

데이터 범위

미국 연료 소매 가격의 주간 시계열 20개를 제공합니다. 일반 휘발유와 도로용 2호 경유 각각에 대해 미국 평균과 9개 지역을 다룹니다. 가격은 미국 갤런당 USD입니다. 이력은 2026년 7월 20일부터 시작하며 매주 월요일 조사 후 추가됩니다. 출처: 미국 에너지정보청. 월간 데이터는 소프트 원자재, 유지 및 유지종자, 금속, 곡물, 에너지, 비료, 임산물, 축산물 및 유제품에 걸친 세계은행 시계열 70개를 포함합니다. 이력은 1960년까지 거슬러 올라가며 일부 시계열은 더 늦게 시작합니다. 이용 가능한 최신 월은 2026년 9월이지만 개별 시계열은 지연되거나 종료되었을 수 있습니다. 보리와 수수는 2020년 8월, 멕시코산 새우는 2023년 10월에 종료되었습니다. 각 시계열의 coverage_end를 확인하세요. 모든 가격은 USD이며 발표된 단위를 그대로 사용합니다. 출처: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

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