실물 상품 시계열 API

지역별 Palmoil FFB 시계열 찾기

엔드포인트 및 요청

REST 엔드포인트

GET /v1/commodities/physical/{commodity}/{country}

계약 요청

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/OIL-PALM-FFB/IDN?area=ID-RI&currency=IDR" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

매개변수

이름	필수	유형	의미
`commodity`	예	경로 · 카탈로그 코드	안정적인 상품 코드입니다. Palmoil 범위에서는 OIL-PALM-FFB를 사용합니다.
`country`	예	경로 · ISO 3166-1 alpha-3	실물 시장을 관할하는 국가입니다. 처음 조사한 국가는 IDN입니다.
`area`	아니요	쿼리 · ISO 3166-2 또는 Narwhal 지역	ID-RI(리아우)와 같은 행정 구역 또는 소스가 정의한 시장 영역입니다.
`currency`	아니요	쿼리 · ISO 4217	발표된 통화로 시계열을 필터링합니다.

응답

계약 예시

{
  "commodity": "OIL-PALM-FFB",
  "country": "IDN",
  "series": [
    {
      "series_id": "id-ri-oil-palm-ffb-smallholder-purchase-agreement",
      "commodity": "OIL-PALM-FFB",
      "country": "IDN",
      "area": "ID-RI",
      "producer_type": "smallholder",
      "producer_arrangement": "purchase_agreement",
      "price_basis": "official_purchase_schedule",
      "currency": "IDR",
      "unit": "kilogram",
      "coverage_start": "2026-08-19",
      "coverage_end": "2026-09-01",
      "latest_released_on": "2026-08-26",
      "schedule_count": 2
    }
  ]
}

필드	유형	필수	의미
`commodity / country`	문자열	예	요청된 실물 시장 범위입니다.
`series`	배열	예	승인된 전체 시계열을 안정적인 series_id 순으로 정렬합니다.
`series_id`	문자열	예	과거 데이터 작업이 사용하는 안정적인 식별 정보입니다.
`area / producer_type / producer_arrangement`	문자열 또는 null	예	정확한 시장 및 생산자 범위입니다.
`coverage_start / coverage_end`	날짜	예	승인된 시계열에서 최초 및 최종 적용 날짜입니다.
`latest_released_on / schedule_count`	날짜 및 정수	예	최근 공식 발표일 및 승인된 일정 수입니다.

오류 및 할당량

400 invalid_query — 코드, 지역, 날짜 범위, 제한 또는 선택기가 잘못되었습니다.
401 invalid_api_key — Bearer 키가 누락되었거나 거부되었습니다.
404 physical_series_not_found — 요청과 일치하는 완전한 승인 데이터가 없습니다.
429 rate_limit_exceeded 또는 quota_exhausted — 공유 허용량이 소진되었습니다.
503 physical_price_unavailable — 완전한 발표로 인터페이스를 안전하게 충족할 수 없습니다.

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

데이터 범위

완전하게 승인된 시계열만 표시됩니다. 처음 선택된 국가는 인도네시아입니다.

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