Available APIs

OpenDataSoft datasets can be accessed by developers through HTTP REST APIs.

The domain http://public.opendatasoft.com will be use to illustrate examples given in this forum.

API Console

Available APIs

The available APIs are listed below.

API Name API Short Description
Dataset search API Search datasets
Dataset lookup API Find a dataset based on its identifier
Records search API Search records within a specific dataset
Analysis API Build advanced aggregations using records of a specific dataset
Download API Efficiently download a large number of records from a specific dataset
Geo clustering API Build geo clusters using records of a specific dataset
Real Time Push API Real time data integration
Multimedia Download API Download multimedia content attached with datasets or records

All these APIs (except the Multimedia download API) return JSON by default. Some of them can return alternate content.

All these APIs (except the Real Time Push API) support cross-domain access from a browser, using CORS (http://en.wikipedia.org/wiki/Cross-origin_resource_sharing). For older browsers or other specific purposes, JSONP (http://en.wikipedia.org/wiki/JSONP) is supported when returning JSON content by adding a callback parameter.

Finding the dataset identifier

You are looking for specific data to build your application but you don’t know yet in which dataset you can find these data?

You can simply use the exploration console by clicking on the “Explore” link in the top page menu. Once you have identified the dataset you need, just go to this dataset’s “Information” tab where you’ll find the dataset id.

HTTP Methods

Except for the Real Time Push API which respects more strictly RESTful concepts, all the APIs endpoints accept GET and POST HTTP methods. GET methods shall be prefered of course. The POST can be used to workaround browsers / libraries / proxies limitations regarding the size of the HTTP URL.

Security

All the APIs are secured using the same authentication and authorization model.

Users can only see what they are allowed to see:

  • Datasets in a domain
  • Records in a dataset

APIs are available both in HTTP and HTTPS. We advise API users to always use the HTTPS endpoint.

The following authentication modes are available:

Note that when you are connected with a Browser session, API calls triggered from that browser will reuse your current credentials.

Quotas

APIs endpoints are subject to quota-based limitations. Contact the domain administrator or the dataset owner when you reach a limit.

The API response contains three headers to indicate the current state of your quota:

  • X-RateLimit-Limit indicates the total number of API calls you can do in a single day (resets at midnight UTC)
  • X-RateLimit-Remaining indicates the number of API calls currently remaining
  • X-RateLimit-Reset indicates the epoch of the next reset time

Errors handling

When an error occurs, a JSON object describing the error is returned by the API.

Example of an error occuring when you reach a quota limit:

HTTP return code:
    403
HTTP response body:
    {
        "errorcode": 10001,
        "error"": "License Violation Exception : You have exceeded your quotas."
    }