pydatagovgr
An unofficial Pythonic client for the official data.gov.gr API. Aims to be an easy, intuitive and out-of-the-box way to:
- find data published by central government, local authorities and public bodies of Greece
- build related products and services.
while being robust, following best-practices and eliminating developer-induced bugs.
The aspiration for this library is to enable users of different backgrounds (academia, industry, students etc.) with an interest to programmatically explore and utilize the open data of data.gov.gr, to do so without having to write-debug-maintain trivial code or worry about that.
Install
The recommended installation is via pip:
pip install pydatagovgr
Quick Usage
You must have an account on data.gov.gr to use the API service. In order to register and request an API token, submit a request in the designated official form here. The procedure is very simple and takes less than 5 minutes.
from pydatagovgr import DataGovClient
gov_client = DataGovClient(token='xoxb-1234-1243')
# fetch the COVID-19 vaccination data
covid_data = gov_client.query('mdg_emvolio')
# fetch data on Greece's internet traffic
traffic_data = gov_client.query('internet_traffic')
# fetch a list of the forest fires
fire_data = gov_client.query('mcp_forest_fires')
Features
The pydatagovgr client supports out-of-the-box all the things you know (and love), such as:
- authentication: properly handles the authentication to data.gov.gr - all you have to do is provide a valid token.
- persistent session: making several requests to data.gov.gr reuses the same underlying connection.
- timeout policy: the client will stop waiting for a response from data.gov.gr after some time. Defaults to 10 sec.
- retry policy: to account for potential server failures of lossy network connections, client automatically retries with an exponential-backoff, to avoid harming the data.gov.gr. Defaults to a maximum of 3 retries.
Also, this library comes with extensive test coverage (100%) of the core functionality. The test suite will constantly improve towards the v1 version.
Not-So-Quick Usage
The data.gov.gr API is currently organized into endpoints called datasets, each available via the query endpoint.
The pydatagovgr client provides a corresponding query method, through which every available dataset can be obtained. You can also pass additional arguments to filter the results accordingly.
from pydatagovgr import DataGovClient
gov_client = DataGovClient(token='xoxb-1234-1243')
# fetch the COVID-19 vaccination data for the 2021
data = gov_client.query('mdg_emvolio', date_from='2021-01-01', date_to='2021-12-31')
You can also use Python objects as arguments:
import datetime
data = gov_client.query('mdg_emvolio',
date_from=datetime.date(2021, 1, 1),
date_to=datetime.date(1, 12, 31))
Apart from the authentication token, you can also configure the timeout and retry policies of your client. For example:
from pydatagovgr import DataGovClient
# this client will stop waiting for a response after 7 seconds
gov_client = DataGovClient(token='xoxb-1234-1243', timeout=7)
# this client will retry at most 3 times, with an exponential-backoff
# (i.e. each retry waits exponentially longer before occurs: 1, 2, 4, 8, 16, 32, 64, ... seconds)
gov_client = DataGovClient(token='xoxb-1234-1243', max_retries=3)
# this client will respect both a timeout policy and a retry policy
gov_client = DataGovClient(token='xoxb-1234-1243', timeout=7, max_retries=3)
How to contribute
If you wish to contribute, this is a great place to start!
License
Distributed under the MIT License.
Acknowledgements
All rights are reserved by the official https://data.gov.gr site, its developers, its maintainers and the Hellenic Government.
caption: the landing page of https://pydatagovgr.readthedocs.io - documentation is being updated live, with each commit to main
13 Jun 20, 2021
8 Jan 03, 2023
94 Dec 15, 2022
3 Jul 13, 2022
1.5k Jan 03, 2023
4 Nov 02, 2022
21 Dec 17, 2022
2 Jan 22, 2022
7 Dec 18, 2022
7.9k Jan 02, 2023
12 Oct 06, 2022
200 Nov 24, 2022
1 Mar 01, 2022
3 Dec 06, 2022
25 May 23, 2022
3 Oct 23, 2021
12 Nov 16, 2022
1 Dec 11, 2021
2 Jan 20, 2022
20 Sep 20, 2022