REST tutorial

OpenML offers a RESTful Web API, with predictive URLs, for uploading and downloading machine learning resources. Try the API Documentation to see examples of all calls, and test them right in your browser.

Getting started

• REST services can be called using simple HTTP GET or POST actions.
• The REST Endpoint URL is https://www.openml.org/api/v1/
• The default endpoint returns data in XML. If you prefer JSON, use the endpoint https://www.openml.org/api/v1/json/. Note that, to upload content, you still need to use XML (at least for now).

Testing

For continuous integration and testing purposes, we have a test server offering the same API, but which does not affect the production server.

• The test server REST Endpoint URL is https://test.openml.org/api/v1/

Error messages

Error messages will look like this:

<oml:error xmlns:oml="http://openml.org/error">
<oml:code>100</oml:code>
<oml:message>Please invoke legal function</oml:message>
<oml:additional_information>Additional information, not always available.</oml:additional_information>
</oml:error>

All error messages are listed in the API documentation. E.g. try to get a non-existing dataset:

• in XML: https://www.openml.org/api_new/v1/data/99999
• in JSON: https://www.openml.org/api_new/v1/json/data/99999

Examples

You need to be logged in for these examples to work.

Download a dataset

• User asks for a dataset using the /data/{id} service. The dataset id is typically part of a task, or can be found on OpenML.org.
• OpenML returns a description of the dataset as an XML file (or JSON). Try it now
• The dataset description contains the URL where the dataset can be downloaded. The user calls that URL to download the dataset.
• The dataset is returned by the server hosting the dataset. This can be OpenML, but also any other data repository. Try it now

Download a flow

• User asks for a flow using the /flow/{id} service and a flow id. The flow id can be found on OpenML.org.
• OpenML returns a description of the flow as an XML file (or JSON). Try it now
• The flow description contains the URL where the flow can be downloaded (e.g. GitHub), either as source, binary or both, as well as additional information on history, dependencies and licence. The user calls the right URL to download it.
• The flow is returned by the server hosting it. This can be OpenML, but also any other code repository. Try it now

Download a task

• User asks for a task using the /task/{id} service and a task id. The task id is typically returned when searching for tasks.
• OpenML returns a description of the task as an XML file (or JSON). Try it now
• The task description contains the dataset id(s) of the datasets involved in this task. The user asks for the dataset using the /data/{id} service and the dataset id.
• OpenML returns a description of the dataset as an XML file (or JSON). Try it now
• The dataset description contains the URL where the dataset can be downloaded. The user calls that URL to download the dataset.
• The dataset is returned by the server hosting it. This can be OpenML, but also any other data repository. Try it now
• The task description may also contain links to other resources, such as the train-test splits to be used in cross-validation. The user calls that URL to download the train-test splits.
• The train-test splits are returned by OpenML. Try it now