Search Wiki

ENGAGE API Reference

API Reference

The ENGAGE platform offers its services via its Application Programming Interface (API). The API provides programmatic access to the ENGAGE Platform system. The API is a REST-style API

WARNING
-------
Should you try the following URLs in your browser, be warned you WILL need to append ?format=json (or xml or yaml) to the URL. Your browser requests application/xml before application/json, so you’ll always get back XML if you don’t specify it.That’s also why it’s recommended that you explore via curl, because you avoid your browser’s opinionated requests.

Using the API you can access most information contained within the ENGAGE platform entities.

Metadata Access (information about the dataset)

To see all the available entities that can be retrieved with the ENGAGE API you can use the following:

http://www.engagedata.eu/api/engage/?format=json

This lists out all the different classes registered in ENGAGE. Each one is listed by the the Entity name and provides the list_endpoint & the schema for the Entity.

For instance to retrieve the full list of the entity “Dataset”:

http://www.engagedata.eu/api/engage/datasets/?format=json

To see the schema of the entity Dataset:

http://www.engagedata.eu/api/engage/datasets/schema/?format=json

To access an individual Dataset:

http://www.engagedata.eu/api/engage/datasets/<dataset id>/?format=json

For instance :

http://www.engagedata.eu/api/engage/datasets/71/?format=json

Returns:

{"author": "Eurostat", "categories": "[u'LFEE']", "country": {"code": "", "name": ""}, "created_date": "2013-06-01T09:19:46.179978", "date_published": null, "description": "Unemployment rate Males vs Females - monthly average", "id": 71, "license": "Eurostat Copyright/Licence Policy", "modified_date": "2014-02-11T08:54:58.217222", "publisher": "Eurostat", "rating_score": 16, "rating_votes": 5, "resource_uri": "/api/engage/datasets/71/", "resources": [{"created_date": "2013-06-01T09:19:46.214593", "description": "Unemployment Men vs Women", "downloads": 0, "file": "https://engagefp7.s3.amazonaws.com/resources/dataset_71/une_rt_m_males_vs_females.csv?Signature=8OlA71HWWJuTlRhepwI5jz9X4co%3D&Expires=1393946674&AWSAccessKeyId=AKIAJCELOSTPLZ56VADA", "format": "", "id": 94, "jsonfile": "", "language": {"code": "en", "name": "Αγγλικά"}, "modified_date": "2013-06-01T10:19:41.209351", "resource_uri": "/api/engage/resource/94/", "uri": ""}], "state": "AA", "title": "Unemployment rates Males vs Females", "uploader": {"date_joined": "2013-03-28T18:54:03.610809", "first_name": "administrator", "id": 1, "last_login": "2014-03-04T04:23:29.254618", "last_name": "engage", "resource_uri": "/api/engage/users/1/", "username": "administrator"}, "url": "http://appsso.eurostat.ec.europa.eu/nui/show.do?dataset=une_rt_m&lang=en", "views": 7}

which in online JSON editor looks like this:

API.jpg
JSON representation of metadata

Data Access

The actual data associated with the dataset is stored within:

  • Object -> resources-> file , for internal datasets stored within engage platform
  • Object-> resources-> uri, for datasets stored in external sites

Independently on whether the data is internal or external, if the data is in tabular format (csv, xls, xlsx) you can access the data with the following command:

http://www.engagedata.eu/api/public/v1/visualization/{dataset_id}/visual/?format=json

For instance

http://www.engagedata.eu/api/public/v1/visualization/71/visual/?format=json

Will have as output

{"items": [{"field_8": "0,0", "field_6": "0,0", "field_7": "0,0", "field_4": "11,0", "field_5": "11,0", "field_2": "10,5", "field_3": "10,5", "field_1": "1.European Union (27 countries)"}, {"field_8": "1,4", "field_6": "0,0", "field_7": "1,4", "field_4": "9,0", "field_5": "7,6", "field_2": "7,6", "field_3": "7,6", "field_1": "Belgium"}, {"field_8": "-0,6", "field_6": "3,0", "field_7": "2,4", "field_4": "13,4", "field_5": "11,0", "field_2": "13,8", "field_3": "10,8", "field_1": "Bulgaria"}, {"field_8": "0,0", "field_6": "-2,2", "field_7": "-2,2", "field_4": "6,2", "field_5": "8,4", "field_2": "6,0", "field_3": "8,2", "field_1": "Czech Republic"}, {"field_8": "-0,4", "field_6": "0,2", "field_7": "-0,2", "field_4": "6,9", "field_5": "7,1", "field_2": "7,7", "field_3": "7,5", "field_1": "Denmark"}, {"field_8": "0,2", "field_6": "0,5", "field_7": "0,7", "field_4": "5,7", "field_5": "5,0", "field_2": "5,7", "field_3": "5,2", 
….
""min": 0, "dataType": "string", "max": 0, "format": {"width": null, "position": 6}, "label": "2013M04 Diff", "uniqueValues": ["0,7", "0,6", "0,5", "0,4", "0,3", "0,0", "1,4", "0,9", "1,1", "2,4", "3,8", "4,6", "2013M04 Diff", "-2,0", "-6,9", "-1,7", "-1,5", "-1,2", "-0,7", "-2,4", "-0,2", "-2,2", "0,8"], "timezone": 0, "dataTypeQualifier": "qualitative"}, {"name": "field_8", "min": 0, "dataType": "string", "max": 0, "format": {"width": null, "position": 7}, "label": "Diff Growth", "uniqueValues": ["0,6", "0,3", "0,2", "0,1", "0,0", "-2,5", "-0,6", "1,4", "-0,4", "-0,2", "1,0", "0,8", "-0,7", "-0,8", "-0,1", "Diff Growth", "-1,0", "-1,1"], "timezone": 0, "dataTypeQualifier": "qualitative"}], "id": 1, "datasetId": "33ad5b83-cb8a-4d6f-916f-a4eb6cbd878a", "description": ""}}

which in online JSON editor looks like this:

APIdata.jpg
JSON representation of data

Filters and offset

With the ENGAGE API you have further filter and offset capabilities.

Filters

You can limit the list results with the parameter limit. For instance to get the first 3 results of the datasets list:

http://www.engagedata.eu/api/engage/datasets/?limit=3&format=json

You can filter the list based on specific fields. For instance to get all the datasets by the user “administrator”:

http://www.engagedata.eu/api/engage/datasets/?user__username=administrator&format=json

Offset

To offset the results page you can use the parameter offset. For instance to the previous example you can see 3 datasets after the first 300:

http://www.engagedata.eu/api/engage/datasets/?limit=3&offset=300&format=json

About the ENGAGE API

The intent of the ENGAGE API is to allow third parties to develop applications that can communicate with the ENGAGE Services infrastructure in order to automatically retrieve datasets or automate dataset publication to the ENGAGE portal. Although provided through a single, unified interface, conceptually the API consists of two components that address different needs and user classes:

The Search API can be accessed by any user and addresses the needs of software developers and mash-up creators who require easy programmatic access to open government data, in order to automatically process or visualize datasets, as well as combine information with other data sources. The Search API provides full read access to the dataset catalogue and implements the same discovery mechanisms as the website. Furthermore, the Search API provides a SPARQL endpoint in order to allow users to query data in a way compliant to the Linked Data principles and standard practices.

The Publish API allows public sector organizations to integrate the publishing workflow in their own dataset management systems and submit or update their datasets to ENGAGE automatically, by offering programmatic access to all dataset management features exposed by the ENGAGE website. For instance, this feature would allow publishers to automatically register or publish their datasets, through their own dataset management system, in the respective national open government data portal as well as the ENGAGE website simultaneously.

The API is complementary to the ENGAGE Services Website and exposes the same functionality in terms of searching, browsing, dataset retrieval and dataset management. Compared to the website, the following restrictions apply to the functionality provided by the ENGAGE API:

Visitors cannot access user information, register new user accounts or update their credentials. Users receive read-only access to submitted suggestions. Users receive read-only access to comments and ratings for all types of content. Users cannot access the documentation. Users cannot subscribe to automatic notification features. However, notifications are available in machine-processable form through RSS feeds by the ENGAGE Services website. Registered users cannot submit curated and modified datasets. The Publish API is exclusive to authorized publishers representing public-sector organizations. However, this functionality may be offered in future releases if there is sufficient demand. The ENGAGE staff cannot moderate content or access administrative features because of particular reasons.