모든 API

과거 상품 가격 API

A commodity prices API for 70 monthly series from the World Bank Pink Sheet. Read copper price history, fertilizer prices and agricultural benchmarks in USD, with units as published. 출처: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

무료 API 키 받기

문서 읽기 →

정상 운영 중99.96% uptime, last 30일357 ms 일반 응답 시간

첫 요청

금속 시리즈 찾기

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

응답 예시

{
  "series": [
    {
      "series_id": "worldbank-cmo-copper",
      "commodity": "copper",
      "commodity_key": "copper",
      "category": "metals",
      "product": "copper",
      "country": "WLD",
      "price_type": "international_benchmark",
      "basis": "settlement price",
      "currency": "USD",
      "unit": "metric_ton",
      "unit_key": "tonne",
      "unit_quantity": "1",
      "frequency": "monthly",
      "description": "Grade A copper, minimum 99.9935% purity, cathodes and wire bar shapes, exchange settlement price.",
      "attribution": "The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0",
      "coverage_start": "1960-01-01",
      "coverage_end": "2026-09-30"
    }
  ]
}

엔드포인트

GET실물 가격 시계열 검색/v1/commodities/physical/series

주간 미국 소매 연료 가격, 일간 석유 및 가스 현물 가격, 월간 원자재 벤치마크를 찾아봅니다.

매개변수

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선택
페이지당 최대 항목 수입니다. 기본값은 100입니다.
cursor선택
이전 페이지의 next_cursor를 동일한 필터 및 limit과 함께 사용하세요. 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[].unit_key문자열
unit_key는 단위를 하나의 표준 표기로 나타낸 값으로, 예를 들면 troy_ounce, barrel, tonne입니다. unit은 출처의 표기를 그대로 유지합니다. 가격이 센트 단위로 표시되면 price_scale은 0.01이며, 가격에 이 값을 곱하면 통화 단위 금액이 됩니다.
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[].commodity_key문자열
commodity_key는 현물, 선물, 예측, 실물 가격 전반에서 gold나 crude-oil처럼 원자재를 같은 이름으로 나타냅니다. 원유에는 benchmark(wti, brent, urals 또는 dubai)도 포함되고, 선물에는 거래소 표준 코드인 exchange_mic이 포함됩니다.
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는 가격 정의를 설명하며 출처가 제공하지 않으면 생략됩니다.

전체 레퍼런스 →

GET실물 가격 시계열 상세 정보 조회/v1/commodities/physical/series/{series_id}

주간 연료 또는 월간 벤치마크 시계열 하나의 정의, 단위, 범위를 조회합니다.

매개변수

series_id필수
fuel-eia-usa-regular-gasoline 또는 worldbank-cmo-copper와 같이 검색에서 반환된 고정 ID를 사용하세요.

응답 필드

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를 사용합니다. 값은 환산하지 않습니다.
unit_key문자열
unit_key는 단위를 하나의 표준 표기로 나타낸 값으로, 예를 들면 troy_ounce, barrel, tonne입니다. unit은 출처의 표기를 그대로 유지합니다. 가격이 센트 단위로 표시되면 price_scale은 0.01이며, 가격에 이 값을 곱하면 통화 단위 금액이 됩니다.
attribution문자열
데이터와 함께 응답의 출처 표시를 유지하세요. 출처: 미국 에너지정보청. 출처: 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. 검색 시 각 시계열의 값을 반환합니다.
commodity_key문자열
commodity_key는 현물, 선물, 예측, 실물 가격 전반에서 gold나 crude-oil처럼 원자재를 같은 이름으로 나타냅니다. 원유에는 benchmark(wti, brent, urals 또는 dubai)도 포함되고, 선물에는 거래소 표준 코드인 exchange_mic이 포함됩니다.
area문자열
area는 지역 범위를 나타내며 전국 시계열에서는 생략됩니다.
country문자열
WLD는 세계 벤치마크를 뜻합니다. EUU는 유럽연합을 뜻합니다. 국가에는 ISO alpha-3 코드를 사용합니다. 미국 연료의 전국 평균에는 USA를 사용합니다.
price_type문자열
연료는 retail_average를 사용합니다. EIA 일간 현물과 월간 시계열은 international_benchmark를 사용하지만, 담배는 import_unit_value를 사용합니다.
basis문자열
basis는 가격 정의를 설명하며 출처가 제공하지 않으면 생략됩니다.
frequency문자열
EIA 석유·가스 현물 가격은 일간, 미국 연료는 주간, World Bank 기준 가격은 월간입니다.

전체 레퍼런스 →

GET최신 실물 가격 조회/v1/commodities/physical/series/{series_id}/latest

관측 기간과 함께 제공되는 최신 주간 연료 또는 월간 벤치마크 가격을 조회합니다.

매개변수

series_id필수
fuel-eia-usa-regular-gasoline 또는 worldbank-cmo-copper와 같이 검색에서 반환된 고정 ID를 사용하세요.

응답 필드

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를 사용합니다. 값은 환산하지 않습니다.
unit_key문자열
unit_key는 단위를 하나의 표준 표기로 나타낸 값으로, 예를 들면 troy_ounce, barrel, tonne입니다. unit은 출처의 표기를 그대로 유지합니다. 가격이 센트 단위로 표시되면 price_scale은 0.01이며, 가격에 이 값을 곱하면 통화 단위 금액이 됩니다.
attribution문자열
데이터와 함께 응답의 출처 표시를 유지하세요. 출처: 미국 에너지정보청. 출처: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
period_start / period_end날짜
시작일과 종료일을 포함하는 관측 날짜입니다. 연료는 두 날짜 모두 월요일 조사일을 사용합니다. 월간 관측값은 2026-09-01부터 2026-09-30까지와 같이 한 달 전체를 다룹니다.
price십진수 문자열
unit_quantity 단위당 해당 시계열의 통화로 발표된 가격입니다. 시계열의 가격 유형 및 basis와 함께 확인하세요.
published_on날짜
발표일입니다. 출처가 제공하지 않으면 생략됩니다.
revision정수
1부터 시작하며 후속 발표에서 해당 기간의 값이 변경되면 증가합니다.

전체 레퍼런스 →

GET실물 가격 이력 조회/v1/commodities/physical/series/{series_id}/observations

기간, 공표 단위, 수정 내역과 함께 주간 연료 또는 월간 원자재 가격 이력을 조회합니다.

매개변수

series_id필수
fuel-eia-usa-regular-gasoline 또는 worldbank-cmo-copper와 같이 검색에서 반환된 고정 ID를 사용하세요.
start선택
시작일을 포함합니다. start와 end를 함께 지정하거나 둘 다 생략하세요.
end선택
종료일은 포함하지 않으며 start보다 늦어야 합니다. 지정한 날짜 범위와 겹치는 관측값을 반환합니다.
limit선택
페이지당 최대 항목 수입니다. 기본값은 100입니다.
cursor선택
이전 페이지의 next_cursor를 동일한 필터 및 limit과 함께 사용하세요. 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를 사용합니다. 값은 환산하지 않습니다.
unit_key문자열
unit_key는 단위를 하나의 표준 표기로 나타낸 값으로, 예를 들면 troy_ounce, barrel, tonne입니다. unit은 출처의 표기를 그대로 유지합니다. 가격이 센트 단위로 표시되면 price_scale은 0.01이며, 가격에 이 값을 곱하면 통화 단위 금액이 됩니다.
attribution문자열
데이터와 함께 응답의 출처 표시를 유지하세요. 출처: 미국 에너지정보청. 출처: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
observations배열
관측값은 오래된 순서로 정렬됩니다. 각 항목에는 period_start, period_end, 소수 문자열 형식의 price와 revision이 포함됩니다. published_on은 선택 사항입니다.
observations[].period_start / observations[].period_end날짜
시작일과 종료일을 포함하는 관측 날짜입니다. 연료는 두 날짜 모두 월요일 조사일을 사용합니다. 월간 관측값은 2026-09-01부터 2026-09-30까지와 같이 한 달 전체를 다룹니다.
observations[].price십진수 문자열
unit_quantity 단위당 해당 시계열의 통화로 발표된 가격입니다. 시계열의 가격 유형 및 basis와 함께 확인하세요.
observations[].published_on날짜
발표일입니다. 출처가 제공하지 않으면 생략됩니다.
observations[].revision정수
1부터 시작하며 후속 발표에서 해당 기간의 값이 변경되면 증가합니다.
next_cursor문자열 또는 null
내부 구조를 해석할 필요 없이 사용하는 연속 조회 토큰입니다. null은 마지막 페이지를 나타냅니다.

전체 레퍼런스 →

활용 사례

내 통화로 보는 가격

환율을 이용해 상품 가격을 내 통화로 환산합니다.

가이드 읽기 →

전체 이력 백필

이력 전체를 페이지 단위로 가져와 파일에 저장하고, 중단되면 이어서 받습니다.

가이드 읽기 →

매일 데이터 가져오기

작은 스크립트를 하루에 한 번 실행하고 결과를 CSV에 추가합니다.

가이드 읽기 →

데이터 범위

소프트 원자재17개 시리즈
유지 및 유지종자11개 시리즈
금속10개 시리즈
곡물9개 시리즈
에너지9개 시리즈
비료5개 시리즈
임산물5개 시리즈
축산물 및 유제품4개 시리즈

출처

세계은행세계은행 상품 가격 데이터(Pink Sheet), CC BY 4.0

자주 묻는 질문

구리 가격 이력은 어떻게 가져오나요?

observations 엔드포인트와 함께 worldbank-cmo-copper를 사용하세요. start와 end를 함께 전달하면 날짜 범위를 선택합니다. 구리 가격은 메트릭 톤당 USD의 월간 십진수 문자열입니다.

이 원자재 API에 비료 가격과 쌀 가격이 포함되나요?

예. 비료 가격은 category=fertilizers, 요소 가격 시리즈는 commodity=urea, 쌀 가격 기준은 commodity=rice를 사용하세요. 검색 결과로 최신 가격과 이력에 쓸 시리즈 ID를 받습니다.

이력은 얼마나 과거까지 제공되나요?

가장 이른 월간 시리즈는 1960년 1월에 시작합니다. 나머지는 더 늦게 시작하며 일부는 종료되었습니다. 시리즈마다 coverage_start와 coverage_end를 확인하세요.

어떤 단위와 라이선스가 적용되나요?

All prices use USD and the published unit and quantity. No unit conversion is applied. Keep the attribution with the data, which is licensed under CC BY 4.0. 출처: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

데이터를 쓰기 전에 무엇을 확인해야 하나요?

A new month is added after each monthly publication. Individual series can lag or have ended. Barley and sorghum end in August 2020; Mexican shrimp ends in October 2023. Check coverage_end before treating a value as current. Most series use WLD for a world benchmark. Others identify a country or the European Union. 출처: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

과거 상품 가격 API