Fetching Series Information

FpmaSerie GET Request

The FpmaSerie GET request is designed to retrieve a comprehensive list of all price series available in the FPMA database. Users can filter the results by various parameters, including country using ISO3 country codes.

Endpoint:

GET https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSerie/

Filter by Country:

To filter the results by specific countries, use the iso3_country_codes query parameter with a comma-separated list of ISO3 country codes:

https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSerie/?iso3_country_codes={ISO3},{ISO3},{ISO3},...

Special Cases

1. Domestic Price Dataset: Returns a list of all the series available in the FAO domestic price dataset i.e. all the series with price type “wholesale” or price type “retail”. Use the following endpoint:

GET https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSerieDomestic/

2. International Price Dataset: Returns a list of all the international price series available in the FAO international price dataset i.e. all the price series with price type “export”. Use this endpoint:

GET https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSerieInternational/

Response Format

The response is in JSON format and includes detailed descriptions of each price series matching the query parameters. Each series entry contains a uuid key, which can be used to fetch specific price data in subsequent requests.

Pagination

The API results are paginated to manage large datasets efficiently. The pagination metadata includes information about the total number of items, as well as URLs for navigating through the pages.

Pagination Parameters

The following query parameters can be used to navigate through paginated results:

Parameter	Description	Example Usage
count	Total number of items available	"count": 3108
next	URL for the next page of results	"next": "https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSerie/?page=2"
previous	URL for the previous page of results	"previous": null
results	Array containing the data items for the current page	"results": [{...}, {...}, ...]

Example Response:

https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSerie/

{
  "count": 3108,
  "next": "https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSerie/?page=2",
  "previous": null,
  "results": [
    {
      "uuid": "abc123",
      "iso3_country_code": "KEN",
      "commodity": "Maize",
      "price_type": "RETAIL"
      // additional data fields
    }
    // additional results
  ]
}

To navigate through the dataset, use the next and previous URLs provided in the response. You can also manually specify the page number using the page query parameter to jump to a specific page:

https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSerie/?page=2

This structure allows users to efficiently access and browse through large sets of data, ensuring that they can easily find and work with the information they need.

Query Parameters

The following query parameters can be used to filter the series:

Query Parameter	Description	Example Usage
periodicity	Filters by periodicity	?periodicity=monthly
start_date	Filters by start date within periodicity	?start_date=2022-01-01
end_date	Filters by end date within periodicity	?end_date=2022-12-31
newerThan	Filters by last price greater than or equal to the date	?newerThan=2022-01-01
olderThan	Filters by last price less than or equal to the date	?olderThan=2022-12-31
iso3_country_codes	Filters by one or more ISO3 country codes	?iso3_country_codes=AFG,AGO
iso3_country_codes_ne	Excludes one or more ISO3 country codes	?iso3_country_codes_ne=AFG,AGO
price_types_ids	Filters by one or more price type IDs	?price_types_ids=1,2
commodity__hs_class_code	Filters by one or more HS class codes for commodities	?commodity__hs_class_code=123,456
sources_ids	Filters by one or more source IDs	?sources_ids=1,2
admin_units	Filters by one or more administrative units	?admin_units=unit1,unit2
market_types	Filters by one or more market types	?market_types=type1,type2
market_types_ne	Excludes one or more market types	?market_types_ne=type1,type2
regional_average	Filters by whether the record has a regional average or not	?regional_average=true or false

Filters can be combined in a query string to narrow down the search results. For example:

https://fpma.fao.org/giews/v4/global/price_module/api/v1/FpmaSerie/?iso3_country_codes=KEN,UGA&start_date=2022-01-01&end_date=2022-12-31&price_types_ids=1,2&page=1&page_size=20

This request fetches data for Kenya and Uganda within the specified date range, includes specific price types, and returns the first page of results with 20 items per page.

Using these filtering and pagination features, users can efficiently access and navigate the FPMA database to retrieve the specific data they need. The following sections will provide detailed examples and practical applications of these features.

Periodicity Property

info

Each series in the API response includes a property called periodicity. This property is an array that details the available data frequencies for the series. The periodicity array can contain multiple objects, each representing a different period (e.g., daily, weekly, monthly). The presence and structure of these periods depend on the available data.

Example of periodicity Property:

"periodicity": [
    {
        "period": "daily",
        "end_date": "2023-12-30",
        "start_date": "2020-01-01"
    },
    {
        "period": "weekly",
        "end_date": "2023-12-29",
        "calculated": true,
        "start_date": "2020-01-03"
    },
    {
        "period": "monthly",
        "end_date": "2023-12-01",
        "calculated": true,
        "start_date": "2020-01-01"
    }
]

Details of the Periodicity Property

• period: Indicates the frequency of the data, such as daily, weekly, or monthly.
• end_date: The last date for which data is available in the specified period.
• start_date: The first date for which data is available in the specified period.
• calculated: A boolean field that indicates whether the data for this period is calculated from higher frequency data. For example:
  • If calculated is true for weekly, the data is derived from daily data.
  • If daily data is unavailable, the monthly data might be calculated from weekly data, and weekly data from daily data.

The periodicity property can contain all three periods, two, one, or none, depending on the availability of the data for the specific series. Users can later use this periodicity data to fetch the prices list from the database based on the required time series frequency.