Palm oil physical series API

Find admitted Palm oil physical series by product and country

Endpoint and request

REST endpoint

GET /v1/commodities/palmoil/physical

Contract request

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 uses commodities_list_palmoil_physical_series. REST and MCP share the same schema, account quota, rights check, and problem shape.

Parameters

Name	Required	Type	Meaning
`product`	No	query · ffb or cpo	Filter by the physical product.
`country`	No	query · ISO 3166-1 alpha-3	Filter by country, such as IDN.
`area`	No	query · area ID	Use an area returned by discovery: ISO 3166-2 where applicable, or a Narwhal-defined nwl-* ID such as nwl-mys-north.
`price_type`	No	query · enum	official_purchase_schedule, government_reference or market_average. The value must be compatible with the product.
`currency`	No	query · currency code	Filter the native currency, such as IDR, USD or MYR. This does not convert prices.
`producer_type`	No	query · smallholder	Applies to Indonesian FFB purchase schedules; not accepted with product=cpo.
`producer_arrangement`	No	query · enum	purchase_agreement or supported_scheme. Applies to Indonesian FFB schedules; not accepted with product=cpo.
`limit`	No	query · integer, 1–500	Maximum series per page. Defaults to 100.
`cursor`	No	query · opaque string	Continue with the returned next_cursor and every original filter and limit unchanged.

Response

Contract example

{
  "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
}

Field	Type	Required	Meaning
`series`	array	Yes	Complete approved series ordered by stable series_id.
`series[].series_id`	string	Yes	Stable identity used by the history operation.
`series[].product / series[].country`	strings	Yes	Product and geographic scope.
`series[].area`	string	No	National series omit area. Regional IDs may use the nwl-* namespace.
`series[].observation_type / series[].period_type`	enums	Yes	scalar or age_schedule; effective or observation. These define the response variant and date semantics.
`series[].price_type / series[].currency / series[].unit`	strings	Yes	The source-defined price type, currency and native unit.
`series[].producer_arrangement`	string	No	Present only on Indonesian FFB age-schedule series when the source names an arrangement. Omitted otherwise.
`series[].frequency / series[].coverage_start / series[].coverage_end`	string and dates	Yes	Cadence and accepted history bounds, not a guarantee of uninterrupted coverage.
`next_cursor`	string or null	Yes	Continuation token, or null when there are no more series.

Errors and quota

400 invalid_query — a code, area, date range, limit, or selector is invalid.
400 invalid_cursor — the cursor is invalid or does not match the series and range.
401 invalid_api_key — the Bearer key is missing or rejected.
409 cursor_expired, the publication changed. Restart pagination without a cursor.
429 rate_limit_exceeded or quota_exhausted — the shared allowance is exhausted.
503 palmoil_unavailable — a complete publication cannot safely satisfy the Interface.

Rejected requests and server errors do not consume monthly quota.

Coverage

Discovery lists admitted Indonesian and Malaysian CPO/FFB series. Filters preserve the product, region, price type and native unit.

Available with a Narwhal API key.