Data access APIs

Introduction

OpenDataSoft's platform provides easy to use tools for developers. These tools provide simple while powerfull data manipulation functions.

Two kind of APIs are currently available:

  • The Fetch API allowing to fetch the whole content of a dataset in a efficient way while still being able to use native filters.
  • The Search API offering powerfull full text search features to navigate across the records of a dataset.

In the following, a dataset is a set of uniform records. A dataset is identified by it's datasetid and is associated with:

  • A title
  • A description
  • A set of arbitrary meta data
  • A schema (the list of fields composing a record)

These APIs allows you to:

  • Fetch or Search datasets
  • Fetch or Search dataset records

Please also note that datasets can be downloaded in CSV or JSON directly from a single web interface.

Fetch API

Fetching datasets

URL: http://%HOSTNAME%/api/fetch/datasets?{*options*}

Where options can be:

  • format: the output format, one of json, jsonp and csv
    • json: json array of datasets, with one json element per dataset.
    • jsonp: same as json with the possibility to pass a callback to bypass cross-scripting issues
    • csv: fetch data in CSV, with columns datasetid, title,description, [meta...])
  • callback: the name of jsonp callback to be used in the response.
  • pretty_print: when using json and jsonp, set the value of true to pretty_print the json output.

Examples:

Fetching records

URL: http://%HOSTNAME%/api/fetch/dataset/{*datasetid*}?{*options*}

Where datasetid is the id of the dataset (as returned by the datasets API calls and options can be:

  • format: the output format, one of json, jsonp and csv
    • json: json array of datasets, with one json element per dataset.
    • jsonp: same as json with the possibility to pass a callback to bypass cross-scripting issues
    • csv: fetch data in CSV, with columns of the original datasets and the columns datasetid and recordid
  • callback: the name of jsonp callback to be used in the response.
  • disp: if set to geo, will be used to display geo coded datasets in an appropriate format {lat: XX, long: xx, data:{...}}
  • pretty_print: when using json and jsonp, set the value of true to pretty_print the json output
  • location: a WGS84 point, indicating a geo position for geo filtering
  • distance: a geo distance expressed in meters

Examples:

Search API

Searching datasets

URL: http://%HOSTNAME%/api/search/datasets?{*options*}

Where options can be:

  • format: the output format, one of json, jsonp and rss
  • callback: the name of jsonp callback to be used in the response.
  • pretty_print: when using json and jsonp, set the value of true to pretty_print the json output.
  • q: full text search query (searches over dataset title, description and meta data)
  • hf: number of search results to retrieve
  • start: id of the first result to retrieve (useful for implementing pagination)

Examples:

Searching records

URL: http://%HOSTNAME%/api/search/dataset/{*datasetid*}?{*options*}

Where datasetid is the id of the dataset (as returned by the datasets API calls and options can be:

  • format: the output format, one of json, jsonp and rss
  • callback: the name of jsonp callback to be used in the response.
  • disp: if set to geo, will be used to display geo coded datasets in an appropriate format {lat: XX, long: xx, data:{...}}
  • pretty_print: when using json and jsonp, set the value of true to pretty_print the json output
  • location: a WGS84 point, indicating a geo position for geo filtering
  • distance: a geo distance expressed in meters
  • q: full text search query (searches over dataset title, description and meta data)
  • hf: number of search results to retrieve
  • start: id of the first result to retrieve (useful for implementing pagination)

Examples: