실물 가격 이력 API

주간 연료 또는 월간 원자재 가격 이력을 기간, 발표된 단위, 개정 정보와 함께 조회합니다.

엔드포인트 및 요청

REST 엔드포인트

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

계약 요청

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/worldbank-cmo-copper/observations?start=2026-07-01&end=2026-10-01&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

매개변수

이름	필수	유형	의미
`series_id`	예	경로 · 문자열	fuel-eia-usa-regular-gasoline 또는 worldbank-cmo-copper와 같이 검색에서 반환된 고정 ID를 사용하세요.
`start`	아니요	쿼리 · YYYY-MM-DD	시작일을 포함합니다. start와 end를 함께 지정하거나 둘 다 생략하세요.
`end`	아니요	쿼리 · YYYY-MM-DD	종료일은 포함하지 않으며 start보다 늦어야 합니다. 지정한 날짜 범위와 겹치는 관측값을 반환합니다.
`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_id": "worldbank-cmo-copper",
  "currency": "USD",
  "unit": "metric_ton",
  "unit_quantity": "1",
  "attribution": "The World Bank: World Bank Commodity Price Data (The Pink Sheet)",
  "observations": [
    {
      "period_start": "2026-07-01",
      "period_end": "2026-07-31",
      "price": "13543",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-08-01",
      "period_end": "2026-08-31",
      "price": "14326",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "price": "14474",
      "published_on": null,
      "revision": 1
    }
  ],
  "next_cursor": null
}

필드	유형	필수	의미
`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
`observations`	배열	예	오래된 순서의 관측값입니다. 각 항목에는 period_start, period_end, 소수 문자열 형식의 price, null이 가능한 published_on, revision이 포함됩니다.
`observations[].period_start / observations[].period_end`	날짜	예	시작일과 종료일을 포함하는 관측 날짜입니다. 연료는 두 날짜 모두 월요일 조사일을 사용합니다. 월간 관측값은 2026-09-01부터 2026-09-30까지와 같이 한 달 전체를 다룹니다.
`observations[].price`	십진수 문자열	예	unit_quantity 단위당 해당 시계열의 통화로 발표된 가격입니다. 시계열의 가격 유형 및 basis와 함께 확인하세요.
`observations[].published_on`	날짜 또는 null	예	확인 가능한 경우의 발표일입니다. 알 수 없으면 null을 유지합니다.
`observations[].revision`	정수	예	1부터 시작하며 후속 발표에서 해당 기간의 값이 변경되면 증가합니다.
`next_cursor`	문자열 또는 null	예	내부 구조를 해석할 필요 없이 사용하는 연속 조회 토큰입니다. null은 마지막 페이지를 나타냅니다.

오류 및 할당량

400 invalid_query, 코드, 지역, 날짜 범위, limit 또는 선택자가 유효하지 않습니다.
400 invalid_cursor, 커서가 유효하지 않거나 요청 필터와 일치하지 않습니다.
400 cursor_expired, 발표 자료가 변경되었습니다. 커서 없이 페이지 조회를 다시 시작하세요.
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 키로 사용할 수 있습니다.