# Faostat Python Package
Tools 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.
# Features
* Read Faostat data and metadata as list of tuples or as pandas dataframe.
* MIT license.
# Documentation
## Getting started:
Requires Python 3.6+
```bash
pip install faostat
```
It is available also from [Anaconda.org][conda].
## Read the list of available datasets:
### As a list of tuples:
```python
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_proxy* is 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 official [Faostat website][faoweb].
Example:
```python
>>> 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:
```python
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_proxy* is 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 official [Faostat website][faoweb].
Example:
```python
>>> df = faostat.list_datasets_df()
>>> df
code label ... state_next year_next
0 QCL Crops and livestock products ... final 2020
1 QI Production Indices ... final 2020
2 QV Value of Agricultural Production ... final 2019
3 FS Suite of Food Security Indicators ... final 2021
4 SCL Supply Utilization Accounts ... final 2020
.. ... ... ... ... ...
70 FA Food Aid Shipments (WFP) ...
71 RM Machinery ...
72 RY Machinery Archive ...
73 RA Fertilizers archive ...
74 PA Producer Prices (old series) ...
```
## 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_proxy* is 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:
```python
faostat.list_pars(code, https_proxy=None)
```
Given the code of a dataset, it reads the parameters and returns them as a list.
Example:
```python
>>> a = faostat.list_pars('QCL')
>>> a
['area', 'element', 'item', 'year']
```
### To retrieve the available values of a parameter for a given dataset:
```python
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:
```python
>> import faostat
>>> 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:
```python
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.
*pars* is optional, but recommended to avoid Timeout Error due to too large query.
To download only a subset of the dataset, you need to pass *pars={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().
Set *show_flags=True* if you want to download also the data flags.
Set *null_values=True* if you want to download also the null data.
*https_proxy* is 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:
```python
>>> 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:
```python
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.
*pars* is optional, but recommended to avoid Timeout Error due to too large query.
To download only a subset of the dataset, you need to pass *pars={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().
Set *show_flags=True* if you want to download also the data flags.
Set *null_values=True* if you want to download also the null data.
*https_proxy* is 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:
```python
>>> data_df = faostat.get_data_df('QCL',pars={'element':[2312, 2313],'item':'221'})
>>> data_df
Domain Code Domain ... Unit Value
0 QCL Crops and livestock products ... ha 0.0
1 QCL Crops and livestock products ... ha 5900.0
2 QCL Crops and livestock products ... ha 6000.0
3 QCL Crops and livestock products ... ha 6000.0
4 QCL Crops and livestock products ... ha 6000.0
... ... ... ... ...
4038 QCL Crops and livestock products ... ha 392722.0
4039 QCL Crops and livestock products ... ha 418436.0
4040 QCL Crops and livestock products ... ha 423949.0
4041 QCL Crops and livestock products ... ha 453034.0
4042 QCL Crops and livestock products ... ha 425302.0
```
## Bug reports and feature requests:
Please [open an issue][issue] or send a message to noemi.cazzaniga [at] polimi.it.
## Disclaimer:
Download and usage of Faostat data is subject to FAO's general [terms and conditions][pol].
## Data sources:
* Faostat database: [online catalog][faoweb].
## References:
* Python package [pandas][pd]: Python Data Analysis Library.
* Python package [eurostat][es]: 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).
[faoweb]: https://www.fao.org/faostat/en/#data
[pol]: https://www.fao.org/contact-us/terms/en/
[issue]: https://bitbucket.org/noemicazzaniga/faostat/issues/new
[pd]: https://pandas.pydata.org/
[es]: https://pypi.org/project/eurostat/
[conda]: https://anaconda.org/noemicazzaniga/faostat
Raw data
{
"_id": null,
"home_page": "",
"name": "faostat",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "faostat statistics data economics science",
"author": "Noemi Emanuela Cazzaniga",
"author_email": "noemi.cazzaniga@polimi.it",
"download_url": "https://files.pythonhosted.org/packages/2b/eb/dfa1a61941dec61f3e42bef8d66e070f5c2a12946160a93e4df624adea4b/faostat-1.0.1.tar.gz",
"platform": null,
"description": "# Faostat Python Package \r\n\r\nTools to read data from Faostat API.\r\nWarning: 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.\r\n\r\n# Features\r\n\r\n* Read Faostat data and metadata as list of tuples or as pandas dataframe.\r\n* MIT license.\r\n\r\n\r\n# Documentation\r\n\r\n\r\n## Getting started:\r\n\r\nRequires Python 3.6+\r\n\r\n```bash\r\npip install faostat\r\n```\r\n\r\nIt is available also from [Anaconda.org][conda].\r\n\r\n\r\n## Read the list of available datasets:\r\n\r\n### As a list of tuples:\r\n\r\n```python\r\nfaostat.list_datasets(https_proxy=None)\r\n```\r\n\r\nRead the available datsets and return a list of tuples.\r\nThe first element of the list contains the header line.\r\n*https_proxy* is supposed to be used only if you need to use a proxy\r\nfor https and should be a list like: `[username, password, url:port]`.\r\nMore information on the available datasets can be found in the official [Faostat website][faoweb].\r\n\r\nExample:\r\n```python\r\n>>> ld = faostat.list_datasets()\r\n>>> ld[0]\r\n('code', 'label', 'date_update', 'note_update', 'release_current', 'state_current', 'year_current', 'release_next', 'state_next', 'year_next')\r\n>>> ld[1:4]\r\n[('QCL', 'Crops and livestock products', '2022-02-17', 'minor revision', '2021-12-21 / 2022-02-17', 'final', '2020', '2022-12', 'final', '2020'),\r\n ('QI', 'Production Indices', '2021-03-18', '', '2021-03-18', 'final', '2019', '2022-04', 'final', '2020'),\r\n ('QV', 'Value of Agricultural Production', '2021-03-18', 'minor revision', '2021-03-18', 'final', '2020', '2022-04', 'final', '2019')]\r\n```\r\n\r\n### As a pandas dataframe:\r\n\r\n```python\r\nfaostat.list_datasets_df(https_proxy=None)\r\n```\r\n\r\nIt reads the available datasets and returns a pandas dataframe.\r\nThe first element of the list contains the header line.\r\n\r\n*https_proxy* is supposed to be used only if you need to use a proxy\r\nfor https and should be a list like: `[username, password, url:port]`.\r\n\r\nMore information on the available datasets can be found in the official [Faostat website][faoweb].\r\n\r\nExample:\r\n```python\r\n>>> df = faostat.list_datasets_df()\r\n>>> df\r\n code label ... state_next year_next\r\n0 QCL Crops and livestock products ... final 2020\r\n1 QI Production Indices ... final 2020\r\n2 QV Value of Agricultural Production ... final 2019\r\n3 FS Suite of Food Security Indicators ... final 2021\r\n4 SCL Supply Utilization Accounts ... final 2020\r\n.. ... ... ... ... ...\r\n70 FA Food Aid Shipments (WFP) ... \r\n71 RM Machinery ... \r\n72 RY Machinery Archive ... \r\n73 RA Fertilizers archive ... \r\n74 PA Producer Prices (old series) ... \r\n```\r\n\r\n\r\n## Check parameters for a given dataset:\r\nFrequently you will need just a subset of a dataset, for instance only one year or country.\r\nYou will therefore use the following functions.\r\n\r\n*https_proxy* is supposed to be used only if you need to use a proxy\r\nfor https and should be a list like: `[username, password, url:port]`.\r\n\r\n### To retrieve the available parameters for a given dataset:\r\n\r\n```python\r\nfaostat.list_pars(code, https_proxy=None)\r\n```\r\n\r\nGiven the code of a dataset, it reads the parameters and returns them as a list.\r\n\r\nExample:\r\n```python\r\n>>> a = faostat.list_pars('QCL')\r\n>>> a\r\n['area', 'element', 'item', 'year']\r\n```\r\n\r\n### To retrieve the available values of a parameter for a given dataset:\r\n\r\n```python\r\nfaostat.get_par(code, par, https_proxy=None)\r\n```\r\n\r\nGiven the code of a dataset and a parameter, it reads the values and returns a dictionary `{label: code}`.\r\n\r\nExample:\r\n```python\r\n>> import faostat\r\n>>> y = faostat.get_par('QCL', 'area')\r\n>>> y\r\n{'Afghanistan': '2',\r\n 'Albania': '3',\r\n 'Algeria': '4',\r\n 'Angola': '7', \r\n etc.}\r\n```\r\n\r\n## Read data from a dataset:\r\n\r\n### As a list of tuples:\r\n\r\n```python\r\nfaostat.get_data(code, pars={}, show_flags=False, null_values=False, https_proxy=None)\r\n```\r\n\r\nGiven the code of a Faostat dataset, it returns the data as a list of tuples.\r\n\r\n*pars* is optional, but recommended to avoid Timeout Error due to too large query.\r\n\r\nTo download only a subset of the dataset, you need to pass *pars={key: value, ...}*:\r\n* key can be one or more of the parameters obtained with list_pars();\r\n* value can be a number, a string or a list, from the codes obtained with get_par().\r\n\r\nSet *show_flags=True* if you want to download also the data flags.\r\n\r\nSet *null_values=True* if you want to download also the null data.\r\n\r\n*https_proxy* is supposed to be used only if you need to use a proxy\r\nfor https and should be a list like: `[username, password, url:port]`.\r\n\r\nExample:\r\n```python\r\n>>> data = faostat.get_data('QCL',pars={'element':[2312, 2313],'item':'221'})\r\n>>> data[40:44]\r\n[('QCL', 'Crops and livestock products', '2', 'Afghanistan', '5312', 'Area harvested', '221', 'Almonds, with shell', '2014', '2014', 'ha', 13703.0),\r\n ('QCL', 'Crops and livestock products', '2', 'Afghanistan', '5312', 'Area harvested', '221', 'Almonds, with shell', '2015', '2015', 'ha', 14676.0),\r\n ('QCL', 'Crops and livestock products', '2', 'Afghanistan', '5312', 'Area harvested', '221', 'Almonds, with shell', '2016', '2016', 'ha', 19481.0),\r\n ('QCL', 'Crops and livestock products', '2', 'Afghanistan', '5312', 'Area harvested', '221', 'Almonds, with shell', '2017', '2017', 'ha', 19793.0)]\r\n```\r\n\r\n### As a pandas dataframe:\r\n\r\n```python\r\nfaostat.get_data_df(code, pars={}, show_flags=False, null_values=False, https_proxy=None)\r\n```\r\n\r\nGiven the code of a Faostat dataset, it returns the data as a pandas dataframe.\r\n\r\n*pars* is optional, but recommended to avoid Timeout Error due to too large query.\r\n\r\nTo download only a subset of the dataset, you need to pass *pars={key: value, ...}*:\r\n* key can be one or more of the parameters obtained with list_pars();\r\n* value can be a number, a string or a list, from the codes obtained with get_par().\r\n\r\nSet *show_flags=True* if you want to download also the data flags.\r\n\r\nSet *null_values=True* if you want to download also the null data.\r\n\r\n*https_proxy* is supposed to be used only if you need to use a proxy\r\nfor https and should be a list like: `[username, password, url:port]`.\r\n\r\nExample:\r\n```python\r\n>>> data_df = faostat.get_data_df('QCL',pars={'element':[2312, 2313],'item':'221'})\r\n>>> data_df\r\n Domain Code Domain ... Unit Value\r\n0 QCL Crops and livestock products ... ha 0.0\r\n1 QCL Crops and livestock products ... ha 5900.0\r\n2 QCL Crops and livestock products ... ha 6000.0\r\n3 QCL Crops and livestock products ... ha 6000.0\r\n4 QCL Crops and livestock products ... ha 6000.0\r\n ... ... ... ... ...\r\n4038 QCL Crops and livestock products ... ha 392722.0\r\n4039 QCL Crops and livestock products ... ha 418436.0\r\n4040 QCL Crops and livestock products ... ha 423949.0\r\n4041 QCL Crops and livestock products ... ha 453034.0\r\n4042 QCL Crops and livestock products ... ha 425302.0\r\n```\r\n\r\n\r\n## Bug reports and feature requests:\r\n\r\nPlease [open an issue][issue] or send a message to noemi.cazzaniga [at] polimi.it.\r\n\r\n\r\n## Disclaimer:\r\n\r\nDownload and usage of Faostat data is subject to FAO's general [terms and conditions][pol].\r\n\r\n\r\n## Data sources:\r\n\r\n* Faostat database: [online catalog][faoweb].\r\n\r\n\r\n## References:\r\n\r\n* Python package [pandas][pd]: Python Data Analysis Library.\r\n* Python package [eurostat][es]: Tools to read data from Eurostat.\r\n\r\n\r\n## History:\r\n\r\n### version 0.1.1 (2022):\r\n\r\n* First official release.\r\n\r\n### version 1.0.1 (Oct 2023):\r\n\r\n* Implemented all the parameters.\r\n* Prevented list_datasets to show the datasets that are not accessible (update_date=None).\r\n\r\n\r\n\r\n[faoweb]: https://www.fao.org/faostat/en/#data\r\n[pol]: https://www.fao.org/contact-us/terms/en/\r\n[issue]: https://bitbucket.org/noemicazzaniga/faostat/issues/new\r\n[pd]: https://pandas.pydata.org/\r\n[es]: https://pypi.org/project/eurostat/\r\n[conda]: https://anaconda.org/noemicazzaniga/faostat\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Faostat Python Package",
"version": "1.0.1",
"project_urls": {
"Source": "https://bitbucket.org/noemicazzaniga/faostat/src/master/"
},
"split_keywords": [
"faostat",
"statistics",
"data",
"economics",
"science"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b31fe6241ff9ae393ce21960a8d51a26483a235b1204f581cb6e8733a16ece0a",
"md5": "4e4f5406b173763c86fefe4355e4634a",
"sha256": "7947c9fe71c5717a24a3683bed2600ef2c859f9d72a899fc2421c4c5ab0dafa7"
},
"downloads": -1,
"filename": "faostat-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e4f5406b173763c86fefe4355e4634a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 4525,
"upload_time": "2023-10-04T07:46:57",
"upload_time_iso_8601": "2023-10-04T07:46:57.263558Z",
"url": "https://files.pythonhosted.org/packages/b3/1f/e6241ff9ae393ce21960a8d51a26483a235b1204f581cb6e8733a16ece0a/faostat-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2bebdfa1a61941dec61f3e42bef8d66e070f5c2a12946160a93e4df624adea4b",
"md5": "5c081d6172432d71af6833f8d9646e89",
"sha256": "e26aa9d2c402806ee582a7cfc90e6b537f2ad23a3217239e298931b19a89bb21"
},
"downloads": -1,
"filename": "faostat-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5c081d6172432d71af6833f8d9646e89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 5183,
"upload_time": "2023-10-04T07:46:59",
"upload_time_iso_8601": "2023-10-04T07:46:59.318840Z",
"url": "https://files.pythonhosted.org/packages/2b/eb/dfa1a61941dec61f3e42bef8d66e070f5c2a12946160a93e4df624adea4b/faostat-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-04 07:46:59",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "noemicazzaniga",
"bitbucket_project": "faostat",
"lcname": "faostat"
}
JSON