Metadata-Version: 2.1
Name: faostat
Version: 0.1.1
Summary: Faostat Python Package
Author: Noemi Emanuela Cazzaniga
Author-email: noemi.cazzaniga@polimi.it
License: MIT
Project-URL: Source, https://bitbucket.org/noemicazzaniga/faostat/src/master/
Keywords: faostat statistics data economics science
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Office/Business
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE.txt

# faostat Python Package 

Tools to read data from Faostat API.

# 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
```


## 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)
```

Read the available datasets and return 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 areas/countries, years, items and elements 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 areas/countries for a given dataset:

```python
faostat.get_areas(code, https_proxy=None)
```

Given the code of a dataset, read the areas and their FAO code and returns a dictionary `{label: code}`.

Example:
```python
>>> a = faostat.get_areas('QCL')
>>> a
{'Afghanistan': '2',
 'Albania': '3',
 'Algeria': '4',
 'Angola': '7', 
 etc.}
```

### To retrieve the available years for a given dataset:

```python
faostat.get_years(code, https_proxy=None)
```

Given the code of a dataset, read the years and returns a dictionary `{label: code}`.

Example:
```python
>> import faostat
>>> y = faostat.get_years('QCL')
>>> y
{'2020': '2020',
 '2019': '2019',
 '2018': '2018',
 '2017': '2017',
 '2016': '2016', 
 etc.}
```

### To retrieve the available items for a given dataset:

```python
faostat.get_items(code, https_proxy=None)
```

Given the code of a dataset, read the items and returns a dictionary `{label: code}`.

Example:
```python
>>> i = faostat.get_items('QCL')
>>> i
{'Agave fibres nes': '800',
 'Almonds, with shell': '221',
 'Anise, badian, fennel, coriander': '711',
 'Apples': '515', 
 etc.}
```

### To retrieve the available elements for a given dataset:

```python
faostat.get_elements(code, https_proxy=None)
```

Given the code of a dataset, read the elements and returns a dictionary `{label: code}`.

Example:
```python
>>> e = faostat.get_elements('QCL')
>>> e
{'Area harvested': '2312',
 'Yield': '2413',
 'Production Quantity': '2510',
 'Stocks': '2111',
 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, 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 following string: 'areas', 'years', 'elements', 'items';
* value can be a number, a string or a list, from the codes obtained with get_areas, get_years, get_elements, get_items.

Set *show_flags=True* if you want to download also the data flags.

*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={'elements':[2312, 2313],'items':'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, 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 following string: 'areas', 'years', 'elements', 'items';
* value can be a number, a string or a list, from the codes obtained with get_areas, get_years, get_elements, get_items.

Set *show_flags=True* if you want to download also the data flags.

*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={'elements':[2312, 2313],'items':'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.



[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/


