All APIs

Physical commodity prices API

Follow palm oil, daily oil and gas prices, weekly US retail fuel prices and monthly commodity benchmarks. Each series keeps its market, published units and observation period.

Online99.96% uptime, last 30 days357 ms typical response

First request

Get the latest palm oil price

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/palmoil/physical/id-ri-oil-palm-ffb-smallholder-purchase-agreement" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
Example response
{
  "series_id": "id-ri-oil-palm-ffb-smallholder-purchase-agreement",
  "currency": "IDR",
  "unit": "kilogram",
  "unit_key": "kilogram",
  "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"
    }
  ]
}

Endpoints

GETDiscover Palm oil physical series/v1/commodities/palmoil/physical

Find admitted Palm oil physical series by product and country.

Parameters

  • productoptional

    Filter by the physical product.

  • countryoptional

    Filter by country, such as IDN.

  • areaoptional

    Use an area returned by discovery: ISO 3166-2 where applicable, or a Narwhal-defined nwl-* ID such as nwl-mys-north.

  • price_typeoptional

    official_purchase_schedule, government_reference or market_average. The value must be compatible with the product.

  • currencyoptional

    Filter the native currency, such as IDR, USD or MYR. This does not convert prices.

  • producer_typeoptional

    Applies to Indonesian FFB purchase schedules; not accepted with product=cpo.

  • producer_arrangementoptional

    purchase_agreement or supported_scheme. Applies to Indonesian FFB schedules; not accepted with product=cpo.

  • limitoptional

    Maximum series per page. Defaults to 100.

  • cursoroptional

    Continue with the returned next_cursor and every original filter and limit unchanged.

Response fields

  • seriesarray

    Complete approved series ordered by stable series_id.

  • series[].series_idstring

    Stable identity used by the history operation.

  • series[].product / series[].countrystrings

    Product and geographic scope.

  • series[].areastring

    National series omit area. Regional IDs may use the nwl-* namespace.

  • series[].observation_type / series[].period_typeenums

    scalar or age_schedule; effective or observation. These define the response variant and date semantics.

  • series[].price_type / series[].currency / series[].unitstrings

    The source-defined price type, currency and native unit.

  • series[].unit_keystring

    unit_key is the unit in one standard spelling, such as troy_ounce, barrel or tonne; unit keeps the source's wording. When a price is quoted in cents, price_scale is 0.01: multiply the price by it to get the amount in currency.

  • series[].producer_arrangementstring

    Present only on Indonesian FFB age-schedule series when the source names an arrangement. Omitted otherwise.

  • series[].frequency / series[].coverage_start / series[].coverage_endstring and dates

    Cadence and accepted history bounds, not a guarantee of uninterrupted coverage.

  • next_cursorstring or null

    Continuation token, or null when there are no more series.


Full reference →
GETGet latest Palm oil physical price/v1/commodities/palmoil/physical/{series_id}

Get the latest accepted Palm oil observation.

Parameters

  • series_idrequired

    Use an ID returned by discovery.

  • price_monthoptional

    MPOB CPO only. Selects one quoted month; defaults to each report's own month.

Response fields

  • series_idstring

    Stable physical-series identity.

  • currency / unitstrings

    Currency and native unit: kilogram for Indonesian FFB schedules, metric_ton for CPO, or one_percent_oer for Malaysian FFB references.

  • unit_keystring

    unit_key is the unit in one standard spelling, such as troy_ounce, barrel or tonne; unit keeps the source's wording. When a price is quoted in cents, price_scale is 0.01: multiply the price by it to get the amount in currency.

  • period_start / period_enddates

    Effective prices use inclusive dates. MPOB uses the report date through the next day, with an exclusive end.

  • revisioninteger

    Revision of the price or complete schedule.

  • price or pricesdecimal string or complete array

    A positive decimal-string price, or a complete prices array with tree_age_min_years, tree_age_max_years and price. Both age bounds are inclusive. Malaysian FFB stays in one_percent_oer.

  • price_monthYYYY-MM

    Required for MPOB CPO quotes; identifies the quoted month; period_start and period_end identify the report-day observation interval.


Full reference →
GETGet Palm oil physical history/v1/commodities/palmoil/physical/{series_id}/observations

Get oldest-first Palm oil observations.

Parameters

  • series_idrequired

    Series returned by discovery.

  • startoptional

    Inclusive range start; supply it with end. Indonesian effective periods are included when they overlap the range. Malaysian daily prices are selected by report date.

  • endoptional

    Exclusive upper bound. It must be later than start.

  • limitoptional

    Maximum observations to return. Defaults to 100; age schedules remain complete.

  • cursoroptional

    Continue with every original parameter unchanged, including series_id, dates, limit and price_month. A changed publication can expire the cursor.

  • price_monthoptional

    MPOB CPO only. Selects one quoted month; defaults to each report's own month.

Response fields

  • series_idstring

    Stable physical-series identity.

  • currency / unitstrings

    Currency and native unit shared by every observation.

  • unit_keystring

    unit_key is the unit in one standard spelling, such as troy_ounce, barrel or tonne; unit keeps the source's wording. When a price is quoted in cents, price_scale is 0.01: multiply the price by it to get the amount in currency.

  • observationsarray

    Period, revision, and scalar value or complete schedule ordered oldest first; MPOB CPO rows retain price_month; Malaysian CPO and FFB rows retain their report-day period_start/period_end.

  • next_cursorstring or null

    Opaque continuation token, or null at the end.


Full reference →

Use cases

Prices in your currency

Convert a commodity price into your own currency with an exchange rate.

Read the guide →

Backfill a full history

Page through all the history, save it to a file and resume if it stops.

Read the guide →

A daily data pull

Run a small script once a day and append the result to a CSV.

Read the guide →

Coverage

Show all 46 commodities

Sources

Related APIs

Spot metals price API

Gold, silver, platinum and palladium spot prices, plus WTI, Brent and copper reference prices.

Explore the API →

Exchange rate API

Current exchange rates, currency conversion and stored rate history.

Explore the API →

Pricing

Free to start. $10 free credits every month, then $2 per 1,000 calls.

See pricing →

FAQ

Which commodities are covered?

Coverage includes palm oil, daily oil and gas prices, weekly US gasoline and diesel retail averages, and monthly commodity benchmarks. Each series has its own market, unit and coverage dates.

Can I combine the series into one price?

Use the series definitions first. Prices with different grades, units, delivery bases, or effective periods are not interchangeable.

What should I check before using the data?

Compare like with like: currency, unit, grade, location, price type and period all matter. Weekly fuel prices are retail averages. Source: U.S. Energy Information Administration. Monthly benchmarks cover 70 series with history back to 1960. Source: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0