.. _agencies:    
    
Data providers
=========================================


Overview
-----------

pandaSDMX supports a number of data providers out of the box. Each data provider
is configured by an item in ``agencies.json`` in the package root. Data providers are
identified by an uppercased string such as "ECB" or "OECD". For each pre-configured data provider, ``agencies.json`` contains
the URL and name of the SDMX API and potentially some additional
metadata about the provider's web API. The configuration information about data
providers is stored in the dict-type class attribute ``_agencies`` of :class:`Request`.
Other data providers can be configured by passing a suitable json-file to the
:meth:`pandasdmx.api.Request.add_agency` which will be used to update the dict
storing the agency configuration. 
  

Pre-configured data providers
-----------------------------------

This section describes the data providers supported
out of the box. The most salient distinction
between data providers derives from the supported API: While OECD and
Australian Bureau of Statistics (ABS) are only supported with regards to their SDMX-JSON APIs, all others
send SDMX-ML messages. SDMX-JSON is confined to
data messages. Hence, pandaSDMX features relating to
structural metadata are unavailable when making requests to OECD or ABS.


`Australian Bureau of Statistics (ABS) <http://www.abs.gov.au/>`_
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
SDMX-JSON only. Start by browsing the website to retrieve the dataflow you're interested in.
Then try to fine-tune a planned data request by providing a valid key (= selection of series from the dataset). 
No automatic validation
can be performed as structural metadata is unavailable.

  
`Eurostat <http://ec.europa.eu/eurostat/web/sdmx-web-services/rest-sdmx-2.1>`_
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

* SDMXML-based API. 
* thousands of dataflows on a wide range of topics.
* No categorisations available.
* Long response times are reported. Increase the timeout attribute to avoid timeout exceptions.

`European Central Bank (ECB) <http://www.ecb.europa.eu/stats/ecb_statistics/co-operation_and_standards/sdmx/html/index.en.html>`_
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
* SDMXML-based API
* supports categorisations of data-flows
* supports preview_data and series-key based key validation
* in general short response times 

`French National Institute for Statistics (INSEE) <http://www.bdm.insee.fr/bdm2/statique?page=sdmx>`_
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  
  * SDMXML-based API.
  
  
`International Monetary Fund (IMF) - SDMX Central only <https://sdmxcentral.imf.org/>`_
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

* SDMXML-based API
* subset of the data available on http://data.imf.org   
     * full IMF data access would require SOAP API support. This feature needs to be added.
     
     
`Organisation for Economic Cooperation and Development (OECD) <http://stats.oecd.org/SDMX-JSON/>`_
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
SDMX-JSON only. Start by browsing the website to retrieve the dataflow you're interested in.
Then try to fine-tune a planned data request by providing a valid key (= selection of series from the dataset). 
No automatic validation
can be performed as structural metadata is unavailable.

  
`United Nations Statistics Division (UNSD) <https://unstats.un.org/home/>`_
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
* SDMXML-based API
* supports preview_data and series-key based key validation


`UNESCO <https://apiportal.uis.unesco.org/getting-started>`_ 
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
* free registration required
* subscription key must be provided either as parameter or HTTP-header with each request   
* SDMXML-based API
 
 
`World Bank - World Integrated Trade Solution (WBG_WITS) <wits.worldbank.org>`_
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

* SDMX-ML-based API.

