Package: faostat
Faostat Python PackageTools to read data from Faostat API.
Warning: Versions 1.x.x still have the functions get_areas, get_years, get_items and get_elements, for backward compatibility, but they are deprecated and will be removed from version 2.x.x.FeaturesRead Faostat data and metadata as list of tuples or as pandas dataframe.MIT license.DocumentationGetting started:Requires Python 3.6+pipinstallfaostatIt is available also fromAnaconda.org.Read the list of available datasets:As a list of tuples:faostat.list_datasets(https_proxy=None)Read the available datsets and return a list of tuples.
The first element of the list contains the header line.https_proxyis supposed to be used only if you need to use a proxy
for https and should be a list like:[username, password, url:port].
More information on the available datasets can be found in the officialFaostat website.Example:>>>ld=faostat.list_datasets()>>>ld[0]('code','label','date_update','note_update','release_current','state_current','year_current','release_next','state_next','year_next')>>>ld[1:4][('QCL','Crops and livestock products','2022-02-17','minor revision','2021-12-21 / 2022-02-17','final','2020','2022-12','final','2020'),('QI','Production Indices','2021-03-18','','2021-03-18','final','2019','2022-04','final','2020'),('QV','Value of Agricultural Production','2021-03-18','minor revision','2021-03-18','final','2020','2022-04','final','2019')]As a pandas dataframe:faostat.list_datasets_df(https_proxy=None)It reads the available datasets and returns a pandas dataframe.
The first element of the list contains the header line.https_proxyis supposed to be used only if you need to use a proxy
for https and should be a list like:[username, password, url:port].More information on the available datasets can be found in the officialFaostat website.Example:>>>df=faostat.list_datasets_df()>>>dfcodelabel...state_nextyear_next0QCLCropsandlivestockproducts...final20201QIProductionIndices...final20202QVValueofAgriculturalProduction...final20193FSSuiteofFoodSecurityIndicators...final20214SCLSupplyUtilizationAccounts...final2020.................70FAFoodAidShipments(WFP)...71RMMachinery...72RYMachineryArchive...73RAFertilizersarchive...74PAProducerPrices(oldseries)...Check parameters for a given dataset:Frequently you will need just a subset of a dataset, for instance only one year or country.
You will therefore use the following functions.https_proxyis supposed to be used only if you need to use a proxy
for https and should be a list like:[username, password, url:port].To retrieve the available parameters for a given dataset:faostat.list_pars(code,https_proxy=None)Given the code of a dataset, it reads the parameters and returns them as a list.Example:>>>a=faostat.list_pars('QCL')>>>a['area','element','item','year']To retrieve the available values of a parameter for a given dataset:faostat.get_par(code,par,https_proxy=None)Given the code of a dataset and a parameter, it reads the values and returns a dictionary{label: code}.Example:>>importfaostat>>>y=faostat.get_par('QCL','area')>>>y{'Afghanistan':'2','Albania':'3','Algeria':'4','Angola':'7',etc.}Read data from a dataset:As a list of tuples:faostat.get_data(code,pars={},show_flags=False,null_values=False,https_proxy=None)Given the code of a Faostat dataset, it returns the data as a list of tuples.parsis optional, but recommended to avoid Timeout Error due to too large query.To download only a subset of the dataset, you need to passpars={key: value, ...}:key can be one or more of the parameters obtained with list_pars();value can be a number, a string or a list, from the codes obtained with get_par().Setshow_flags=Trueif you want to download also the data flags.Setnull_values=Trueif you want to download also the null data.https_proxyis supposed to be used only if you need to use a proxy
for https and should be a list like:[username, password, url:port].Example:>>>data=faostat.get_data('QCL',pars={'element':[2312,2313],'item':'221'})>>>data[40:44][('QCL','Crops and livestock products','2','Afghanistan','5312','Area harvested','221','Almonds, with shell','2014','2014','ha',13703.0),('QCL','Crops and livestock products','2','Afghanistan','5312','Area harvested','221','Almonds, with shell','2015','2015','ha',14676.0),('QCL','Crops and livestock products','2','Afghanistan','5312','Area harvested','221','Almonds, with shell','2016','2016','ha',19481.0),('QCL','Crops and livestock products','2','Afghanistan','5312','Area harvested','221','Almonds, with shell','2017','2017','ha',19793.0)]As a pandas dataframe:faostat.get_data_df(code,pars={},show_flags=False,null_values=False,https_proxy=None)Given the code of a Faostat dataset, it returns the data as a pandas dataframe.parsis optional, but recommended to avoid Timeout Error due to too large query.To download only a subset of the dataset, you need to passpars={key: value, ...}:key can be one or more of the parameters obtained with list_pars();value can be a number, a string or a list, from the codes obtained with get_par().Setshow_flags=Trueif you want to download also the data flags.Setnull_values=Trueif you want to download also the null data.https_proxyis supposed to be used only if you need to use a proxy
for https and should be a list like:[username, password, url:port].Example:>>>data_df=faostat.get_data_df('QCL',pars={'element':[2312,2313],'item':'221'})>>>data_dfDomainCodeDomain...UnitValue0QCLCropsandlivestockproducts...ha0.01QCLCropsandlivestockproducts...ha5900.02QCLCropsandlivestockproducts...ha6000.03QCLCropsandlivestockproducts...ha6000.04QCLCropsandlivestockproducts...ha6000.0...............4038QCLCropsandlivestockproducts...ha392722.04039QCLCropsandlivestockproducts...ha418436.04040QCLCropsandlivestockproducts...ha423949.04041QCLCropsandlivestockproducts...ha453034.04042QCLCropsandlivestockproducts...ha425302.0Bug reports and feature requests:Pleaseopen an issueor send a message to noemi.cazzaniga [at] polimi.it.Disclaimer:Download and usage of Faostat data is subject to FAO's generalterms and conditions.Data sources:Faostat database:online catalog.References:Python packagepandas: Python Data Analysis Library.Python packageeurostat: Tools to read data from Eurostat.History:version 0.1.1 (2022):First official release.version 1.0.1 (Oct 2023):Implemented all the parameters.Prevented list_datasets to show the datasets that are not accessible (update_date=None).version 1.0.2 (Oct 2023):Bug fix: build.