faodata 1.1
Download data from the Food and Agriculture Organisation (FAO)
License: MIT
Keywords: FAO,Web Service,GIS

faodata
=======

A simple python interface to download data from the Food and Agriculture Organisation (FAO).

What is faodata?
~~~~~~~~~~~~~~~~

-  faodata is a simple python interface to find and request data from
   the Food and Agriculture organization of the United Nations
   (`FAO <http://faostat3.fao.org/home/E>`__).
-  The package uses the `FAO API <http://api.data.fao.org/1.0/>`__.
-  Country boundaries that are used to plot data are from `Natural Earth
   (1:110m
   resolution) <http://www.naturalearthdata.com/downloads/110m-cultural-vectors/>`__

Installation
~~~~~~~~~~~~

``pip install faodata`` or download the `source
code <https://bitbucket.org/jlerat/faodata>`__ and
``python setup.py install``

Basic use
~~~~~~~~~

To download data, the id of the database, dataset and fields are
required:

-  To get the list of FAO databases:

   .. code:: Python

       from faodata import faodownload
       databases = faodownload.get_databases()

-  To get the list of FAO datasets in a given database (e.g. faostat):

   .. code:: python

       database_id = 'faostat'
       datasets = faodownload.get_datasets(database_id)

-  To get the list of FAO fields in a given dataset (e.g. live-prod):

   .. code:: python

       database_id = 'faostat'
       dataset_id = 'live-prod'
       fields = faodownload.get_fields(database_id, dataset_id)

When all the previous elements are known, the download procedure is

.. code:: python

    database_id = 'faostat'
    dataset_id = 'live-prod'
    field_id = 'm5111'

    # Define the year (if None, all years are retrieved)
    year = 2010

    # Define country (if None, all countries are retrieved)
    # The country id is the ISO3 code
    # see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 
    country_id = None

    # Get data
    data = faodownload.get_data(database_id, dataset_id, field_id, country=country_id, year=year)

When data is downloaded, it can be displayed on a world map

.. code:: Python

    import numpy as np
    import matplotlib.pyplot as plt
    from mpl_toolkits import basemap
    from faodata import faodownload, faomap

    # Download data
    database_id = 'faostat'
    dataset_id = 'live-prod'
    field_id = 'm5111'
    year = 2013
    data = faodownload.get_data(database_id, dataset_id, field_id, year=year)

    # Select data
    item = 'Cattle'
    idx = data['Item'] == item
    data = data.loc[idx, ['country', 'value']]

    # Instantiate matplotlib and basemap objects
    plt.close('all')
    fig, ax = plt.subplots()
    map = basemap.Basemap(projection='robin', \
            lon_0=10, lat_0=50, ax = ax)

    map.drawcoastlines(color='grey')
    map.drawcountries(color='grey')

    # Categorize data according to percentiles
    cat = [np.percentile(data['value'], pp) \
            for pp in range(10, 100, 10)]

    # Draw plot
    faomap.plot(map, data, cat, ndigits=0)

    map.ax.legend(loc=3)
    ax.set_title('%s population, %d' % (item, year),
            fontsize=15)

    # Add a footer to the figure to 
    # indicate data source
    faomap.mapfooter(fig, database_id, dataset_id, field_id)

More examples in the `example folder <https://bitbucket.org/jlerat/faodata/downloads>`__ directory.