Using the API¶
An API (Application Programming Interface) is an interface for programs to communicate and exchange data.
To know more about what APIs are and why and how they are used, you can read the article "You don’t need analogies to understand APIs" written by one of our Opendatasoft developers.
Opendatasoft provides access to 6 APIs, that can be put into 3 categories:
- ODS Search API v1 and ODS Search API v2: Opendatasoft's own APIs, used internally by the platform and the ODS widgets
- Triple Pattern Fragments API: ODS API for triple pattern querying over datasets from Opendatasoft portals
- OData, WFS and CSW, 3 standard protocols supported and provided by Opendatasoft
All these APIs provide access to any data pushed to the platform, no matter their source or format, as long as the security rules defined by the data owner allow that access.
These APIs can be used, for example, to search for datasets and data, to compute analysis or to perform geographic aggregations. Still developer-oriented, but for more concrete examples of what can be done with APIs: applications as data reuses. Some of Opendatasoft customers have indeed seen their datasets being reused through their API, to create applications (i.e. Qui dit miam ! and Y'A D Frites! 2 applications that display the school canteen menu of French cities, Toulouse, Rennes and Saint-Malo).
Before using any of the available APIs, it is very important to be familiar with the nature of this data. Everything within the platform is built according to a tree structure (there are of course more types of data within the platform, but they are only relevant in very specific contexts). Opendatasoft can thus be seen as such:
- The Opendatasoft platform is a network of Opendatasoft portals.
- A portal provides a catalog of all of its datasets.
- Each dataset is defined by a dictionary of metadata, a data schema (specifying fields names and types) and a collection of records.
- Each record provides values for each of the dataset's fields.
This ODS Search API is used internally by the Opendatasoft platform and widgets. To develop an application, we recommand using this API.
- The ODS Search API v2 introduces a better implementation of REST principles. Each API entry-point provides links to easily navigate between linked resources (HATEOAS).
- Key changes in the v2:
- a more complete query language (ODSQL) is available, with new functions and arithmetic expressions
- special filters (such as geofilter and facet filters) are now directly integrated to ODSQL, in the
geofilter.distance='42,1,100'is replaced by
- the aggregation API (former analyze API) now shares the same structure and ODSQL language as the Search API, and is available on both the catalog (to aggregate datasets) and the dataset (to aggregate records) APIs
- exporters have their own entry-point under
- navigation search (former facet search) and standard search are completely splitted
Triple Pattern Fragments¶
The Triple Pattern Fragments (TPF) API enables dataset querying in Resource Description Framework (RDF) format. This work is still in progress and is part of a PhD that aims to improve Opendatasoft datasets quality using semantic web technologies.
OData, WFS and CSW¶
OData, WFS and CSW refer to other standards implemented by the platform. We recommand to users who are not familiar with these 3 APIs to stick to the ODS Search API since it provides the most comprehensive access to the data.
- OData: standard for REST APIs that provides a common language to be used across APIs to perform requests. The trade-off for this norm's generic approach is its higher complexity compared to traditional custom REST APIs. Opendatasoft has implemented this norm for the simple operations (searching for datasets and records) ; for the more complex ones (analysis, aggregations, geographic computations etc.) our ODS Search APIs (v1 and v2) must be used.
- WFS and CSW: standards focusing on geographic data. They are especially relevant for example to interface the platform with other GIS software.