팜유 실물 시계열 API

상품과 국가별로 승인된 팜유 실물 가격 시계열 찾기

엔드포인트 및 요청

REST 엔드포인트

GET /v1/commodities/palmoil/physical

계약 요청

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/palmoil/physical?product=ffb&country=IDN&area=ID-RI&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

매개변수

이름	필수	유형	의미
`product`	아니요	쿼리 · ffb 또는 cpo	실물 상품으로 필터링합니다.
`country`	아니요	쿼리 · ISO 3166-1 alpha-3	IDN과 같은 country로 필터링합니다.
`area`	아니요	쿼리 · 지역 ID	검색 API가 반환한 지역을 사용합니다. 해당하는 경우 ISO 3166-2를 사용하고, 그렇지 않으면 nwl-mys-north와 같은 Narwhal 정의 nwl-* ID를 사용합니다.
`price_type`	아니요	쿼리 · 열거형	official_purchase_schedule, government_reference 또는 market_average입니다. 값은 상품과 호환되어야 합니다.
`currency`	아니요	쿼리 · 통화 코드	IDR, USD 또는 MYR와 같은 원래 통화로 필터링합니다. 가격을 환산하지는 않습니다.
`producer_type`	아니요	쿼리 · 소규모 생산자	인도네시아 FFB 구매 가격표에 적용되며 product=cpo와 함께 사용할 수 없습니다.
`producer_arrangement`	아니요	쿼리 · 열거형	purchase_agreement 또는 supported_scheme입니다. 인도네시아 FFB 가격표에 적용되며 product=cpo와 함께 사용할 수 없습니다.
`limit`	아니요	쿼리 · 정수, 1~500	페이지당 최대 시계열 수입니다. 기본값은 100입니다.
`cursor`	아니요	쿼리 · 불투명 문자열	반환된 next_cursor와 모든 원래 필터 및 limit를 그대로 유지해 계속합니다.

응답

계약 예시

{
  "series": [
    {
      "series_id": "id-ri-oil-palm-ffb-smallholder-purchase-agreement",
      "product": "ffb",
      "observation_type": "age_schedule",
      "period_type": "effective",
      "country": "IDN",
      "area": "ID-RI",
      "producer_arrangement": "purchase_agreement",
      "price_type": "official_purchase_schedule",
      "currency": "IDR",
      "unit": "kilogram",
      "coverage_start": "2026-08-19",
      "coverage_end": "2026-09-01",
      "frequency": "weekly"
    }
  ],
  "next_cursor": null
}

필드	유형	필수	의미
`series`	배열	예	승인된 전체 시계열을 안정적인 series_id 순으로 정렬합니다.
`series[].series_id`	문자열	예	과거 데이터 작업이 사용하는 안정적인 식별 정보입니다.
`series[].product / series[].country`	문자열	예	상품 및 지리적 범위입니다.
`series[].area`	문자열	아니요	전국 시계열에서는 area를 생략합니다. 지역 ID는 nwl-* 네임스페이스를 사용할 수 있습니다.
`series[].observation_type / series[].period_type`	열거형	예	scalar 또는 age_schedule; effective 또는 observation입니다. 응답 유형과 날짜 의미를 정의합니다.
`series[].price_type / series[].currency / series[].unit`	문자열	예	출처가 정의한 가격 유형, 통화 및 원래 단위입니다.
`series[].producer_arrangement`	문자열	아니요	출처가 약정 유형을 명시한 인도네시아 FFB 수령별 가격표 시계열에만 포함됩니다. 그 외에는 생략됩니다.
`series[].frequency / series[].coverage_start / series[].coverage_end`	문자열 및 날짜	예	업데이트 주기와 승인된 과거 데이터의 제공 범위이며, 해당 범위에 데이터 공백이 없음을 보장하지는 않습니다.
`next_cursor`	문자열 또는 null	예	다음 페이지 토큰이며, 더 이상 시계열이 없으면 null입니다.

오류 및 할당량

400 invalid_query — 코드, 지역, 날짜 범위, 제한 또는 선택기가 잘못되었습니다.
400 invalid_cursor — 커서가 잘못되었거나 시계열 및 범위와 일치하지 않습니다.
401 invalid_api_key — Bearer 키가 누락되었거나 거부되었습니다.
409 cursor_expired, 발표 자료가 변경되었습니다. 커서 없이 페이지 조회를 다시 시작하세요.
429 rate_limit_exceeded 또는 quota_exhausted — 공유 허용량이 소진되었습니다.
503 palmoil_unavailable — 완전한 발표로 인터페이스를 안전하게 충족할 수 없습니다.

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

데이터 범위

검색 API에는 승인된 인도네시아 및 말레이시아 CPO/FFB 시계열이 표시됩니다. 필터는 상품, 지역, 가격 유형 및 원래 단위를 그대로 유지합니다.

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