Physical commodity series API

Find Palmoil FFB series by area

Endpoint and request

REST endpoint

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

Contract request

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

Parameters

Name	Required	Type	Meaning
`commodity`	Yes	path · catalogue code	Stable commodity code. The Palmoil slice uses OIL-PALM-FFB.
`country`	Yes	path · ISO 3166-1 alpha-3	Country that owns the physical market. The first researched country is IDN.
`area`	No	query · ISO 3166-2 or Narwhal area	Administrative or source-defined market area, such as ID-RI for Riau.
`currency`	No	query · ISO 4217	Filter series by their published monetary currency.

Response

Contract example

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

Field	Type	Required	Meaning
`commodity / country`	strings	Yes	The requested physical-market scope.
`series`	array	Yes	Complete approved series ordered by stable series_id.
`series_id`	string	Yes	Stable identity used by the history operation.
`area / producer_type / producer_arrangement`	strings or null	Yes	The exact market and producer scope.
`coverage_start / coverage_end`	dates	Yes	First and last effective dates in the approved series.
`latest_released_on / schedule_count`	date and integer	Yes	Latest official release date and number of approved schedules.

Errors and quota

400 invalid_query — a code, area, date range, limit, or selector is invalid.
401 invalid_api_key — the Bearer key is missing or rejected.
404 physical_series_not_found — no complete approved data matches the request.
429 rate_limit_exceeded or quota_exhausted — the shared allowance is exhausted.
503 physical_price_unavailable — a complete publication cannot safely satisfy the Interface.

Rejected requests and server errors do not consume monthly quota.

Coverage

Only complete approved series appear. The first selected country is Indonesia.

Public access is not open yet.