과거 팜유 실물 API

가장 오래된 순서로 팜유 관측값 가져오기

엔드포인트 및 요청

REST 엔드포인트

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

계약 요청

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/palmoil/physical/id-ri-oil-palm-ffb-smallholder-purchase-agreement/observations?start=2026-08-01&end=2026-09-02&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

매개변수

이름	필수	유형	의미
`series_id`	예	경로 · 고정 Narwhal ID	검색 API가 반환한 시계열입니다.
`start`	아니요	쿼리 · YYYY-MM-DD	범위 시작일은 포함되며 end와 함께 제공해야 합니다. 인도네시아 유효 기간은 범위와 겹치면 포함되고, 말레이시아 일일 가격은 보고일로 선택됩니다.
`end`	아니요	쿼리 · YYYY-MM-DD	배타적 상한입니다. start보다 늦어야 합니다.
`limit`	아니요	쿼리 · 정수, 1~500	반환할 최대 관측값 수입니다. 기본값은 100이며 수령별 가격표는 항상 완전하게 유지됩니다.
`cursor`	아니요	쿼리 · 불투명 문자열	series_id, 날짜, limit, price_month를 포함한 모든 원래 매개변수를 그대로 유지해 계속합니다. 공개 데이터가 변경되면 커서가 만료될 수 있습니다.
`price_month`	아니요	쿼리 · YYYY-MM	MPOB CPO에만 해당합니다. 가격 대상 월 하나를 선택하며, 기본값은 각 보고서 자체의 월입니다.

응답

계약 예시

{
  "series_id": "id-ri-oil-palm-ffb-smallholder-purchase-agreement",
  "currency": "IDR",
  "unit": "kilogram",
  "observations": [
    {
      "period_start": "2026-08-26",
      "period_end": "2026-09-01",
      "revision": 1,
      "prices": [
        {
          "tree_age_min_years": 3,
          "tree_age_max_years": 3,
          "price": "2998.31"
        },
        {
          "tree_age_min_years": 4,
          "tree_age_max_years": 4,
          "price": "3347.20"
        },
        {
          "tree_age_min_years": 5,
          "tree_age_max_years": 5,
          "price": "3595.38"
        },
        {
          "tree_age_min_years": 6,
          "tree_age_max_years": 6,
          "price": "3734.94"
        },
        {
          "tree_age_min_years": 7,
          "tree_age_max_years": 7,
          "price": "3818.86"
        },
        {
          "tree_age_min_years": 8,
          "tree_age_max_years": 8,
          "price": "3865.46"
        },
        {
          "tree_age_min_years": 9,
          "tree_age_max_years": 9,
          "price": "3878.72"
        },
        {
          "tree_age_min_years": 10,
          "tree_age_max_years": 20,
          "price": "3836.93"
        },
        {
          "tree_age_min_years": 21,
          "tree_age_max_years": 21,
          "price": "3770.94"
        },
        {
          "tree_age_min_years": 22,
          "tree_age_max_years": 22,
          "price": "3695.31"
        },
        {
          "tree_age_min_years": 23,
          "tree_age_max_years": 23,
          "price": "3609.33"
        },
        {
          "tree_age_min_years": 24,
          "tree_age_max_years": 24,
          "price": "3544.29"
        },
        {
          "tree_age_min_years": 25,
          "tree_age_max_years": 25,
          "price": "3490.84"
        },
        {
          "tree_age_min_years": 26,
          "tree_age_max_years": 26,
          "price": "3471.62"
        },
        {
          "tree_age_min_years": 27,
          "tree_age_max_years": 27,
          "price": "3441.82"
        },
        {
          "tree_age_min_years": 28,
          "tree_age_max_years": 28,
          "price": "3385.41"
        },
        {
          "tree_age_min_years": 29,
          "tree_age_max_years": 29,
          "price": "3344.02"
        },
        {
          "tree_age_min_years": 30,
          "tree_age_max_years": 30,
          "price": "3249.41"
        }
      ]
    }
  ],
  "next_cursor": null
}

필드	유형	필수	의미
`series_id`	문자열	예	안정적인 실물 시계열 식별 정보입니다.
`currency / unit`	문자열	예	모든 관측값에 공통으로 적용되는 통화와 원래 단위입니다.
`observations`	배열	예	기간, 개정, 스칼라 값 또는 완전한 가격표는 가장 오래된 순서로 정렬됩니다. MPOB CPO 행은 price_month를 유지하고, 말레이시아 CPO 및 FFB 행은 보고일의 period_start/period_end를 유지합니다.
`next_cursor`	문자열 또는 null	예	불투명한 연속 토큰이며 마지막에는 null입니다.

오류 및 할당량

400 invalid_query — 코드, 지역, 날짜 범위, 제한 또는 선택기가 잘못되었습니다.
400 invalid_cursor — 커서가 잘못되었거나 시계열 및 범위와 일치하지 않습니다.
401 invalid_api_key — Bearer 키가 누락되었거나 거부되었습니다.
403 plan_upgrade_required — 요청 기간 또는 시작이 요금제의 과거 데이터 범위(Free 12개월, Basic 5년, Pro 전체)보다 이전입니다.
404 palmoil_series_not_found — 요청과 일치하는 완전한 승인 데이터가 없습니다.
409 cursor_expired, 발표 자료가 변경되었습니다. 커서 없이 페이지 조회를 다시 시작하세요.
429 rate_limit_exceeded 또는 quota_exhausted — 공유 허용량이 소진되었습니다.
503 palmoil_unavailable — 완전한 발표로 인터페이스를 안전하게 충족할 수 없습니다.

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

데이터 범위

승인된 과거 데이터의 범위는 시계열마다 다릅니다. 말레이시아 과거 자료에는 보고서가 누락된 구간이 문서에 명시되어 있으며, 인도네시아 FFB 데이터 범위는 지역마다 다릅니다.

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