Skip to main content

Fetching Price Series Data

FpmaSeriePrice GET Request​

The FpmaSeriePrice GET request retrieves an array of prices for one or more specified series, based on the parameters provided. This API allows users to fetch price data for selected series with a specified periodicity, offering flexibility in data retrieval.

Endpoint:

GET https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSeriePrice/?uuid__in=uuid1,uuid2,...&periodicity={periodicity}

Parameters:

  • uuid__in: A comma-separated list of UUIDs representing the price series to fetch.
  • periodicity: The desired periodicity of the data, which must be one of the available periodicities mentioned in the series description returned by the FpmaSerie GET request (e.g., daily, weekly, monthly).

Price Value Options​

The API provides three different formats for price values, depending on the users' requirements:

  1. price_value: The original value in the local currency and measure unit, as specified by currency and measure_unit_label in the series description.
  2. price_value_real: The value adjusted to real terms using the Consumer Price Index (CPI) for the corresponding month.
  3. price_value_dollar: The value converted to USD terms using the exchange rate for the corresponding month.

Conversion Factor​

The conversion_factor in each data point indicates how the original measure unit can be converted to kilograms (Kg). If the original measure unit is convertible to Kg, the conversion_factor provides the multiplier to perform this conversion. For instance:

  • A conversion_factor of 1 means the price is already expressed per Kg.
  • A conversion_factor other than 1 should be used to convert the price_value to a per Kg equivalent. For example, if the original measure is in tons and the conversion_factor is 0.001, multiplying the price_value by 0.001 will convert the price to a per Kg value.
Data Consistency

The availability of real and dollar-adjusted prices depends on the data quality and completeness. Not all series may have real or dollar-adjusted values, so users should handle these cases accordingly.

Sample Response​

https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSeriePrice/?uuid__in=uuid1,uuid2,...&periodicity={periodicity}
{
"count": 12,
"next": null,
"previous": null,
"results": [
    {
    "uuid": "10cc6802-cf70-4114-8cdf-45be23d6b2ee",
    "datapoints": [
        {
        "id": 5167078,
        "price_value": 50,
        "price_value_real": null,
        "price_value_dollar": null,
        "conversion_factor": 1,
        "date": "2024-07-01",
        "periodicity": "monthly"
        }
        // additional datapoints
    ]
    }
    // additional series
]
}

Important Considerations​

Data Load Management

Fetching data for a large number of series in a single request can be resource-intensive and may lead to timeouts. To avoid performance issues, it is recommended to request data in smaller batches and then merge the results. This approach helps manage computational resources effectively and ensures successful data retrieval.
For more information on batching requests, refer to the Pagination Guide.