Datasets API Quick Start Guide Mendeley Developer Portal

Datasets published on Mendeley Data are available through the Datasets API. A dataset is a collection of research data files, alongside some metadata about the dataset itself. You can create and edit a private draft dataset, but once published, it becomes a permanent unchanging public record. Once published, it can be referenced from other sources using its DOI, which is made up of the dataset’s unique identifier (e.g. 322y43x9b7) and its version (e.g. 1).

In the following examples, we will assume you have already retrieved an OAuth token to grant access to Mendeley APIs. Wherever you see $TOKEN in these examples, you should substitute your own OAuth token.

Retrieve the ids of published datasets

By default the API returns a list of dataset ids.

See steps involved

curl -X GET "https://api.mendeley.com/datasets"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-public-dataset.1+json"

Retrieving a dataset by id

You can retrieve full details of a published dataset using its id (xrpfs4r78h in the following example).

See steps involved

curl -X GET "https://api.mendeley.com/datasets/xrpfs4r78h"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-public-dataset.1+json"

This dataset has multiple published versions. By default, the latest version is returned. You can retrieve a specific version by adding a version query parameter:

curl -X GET "https://api.mendeley.com/datasets/xrpfs4r78h?version=2"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-public-dataset.1+json"

Avoiding multiple API calls

By default, the API returns only the id for each published dataset. You can avoid querying the API again to retrieve more details by specifying the fields you would like.

See steps involved

curl -X GET "https://api.mendeley.com/datasets?fields=results.id,results.version,results.name"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-public-dataset.1+json"

Fields can be extracted from deep inside the dataset structure. This retrieves the last names of all contributors:

curl -X GET "https://api.mendeley.com/datasets?fields=results.name,results.contributors.last_name"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-public-dataset.1+json"

Using a * at any level returns all fields below that level. You can use this to retrieve all dataset fields. This can result in large responses, so it’s better to retrieve just the fields you need.

curl -X GET "https://api.mendeley.com/datasets?fields=results.*"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-public-dataset.1+json"

Searching for datasets linked to an article or a journal

You can find datasets linked to an article if you have the article DOI (10.1093/nc/niv009 in this example).

See steps involved

Note that the DOI, as for all other query parameters, needs to be URL-escaped. That is, characters with a special meaning in a URL should be replaced with %xx, where xx are the hexadecimal representation of the ASCII value of the character.

curl -X GET "https://api.mendeley.com/datasets?article_doi=10.1093%2Fnc%2Fniv009"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-public-dataset.1+json"

You can find datasets linked to a journal if you have the journal ISSN (2057-2107 in this example).

curl -X GET "https://api.mendeley.com/datasets?issn=2057-2107"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-public-dataset.1+json"

Creating a new dataset

A dataset is created in draft form. The draft can be edited until it is published. A draft dataset includes the version and DOI it will have when published, but the DOI is not registered (and therefore cannot be used to find the dataset) until the dataset is published.

See steps involved

The only mandatory field for a new draft is the name, but most fields are mandatory for publishing. So, to create a new minimal dataset, we can do:

curl -X POST "https://api.mendeley.com/datasets/drafts"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-draft-dataset.1+json"
	-H "Content-Type: application/vnd.mendeley-dataset-creation-request.1+json"
	-d '{"name":"My dataset"}'

Editing a draft

Editing a draft (with id b7nzjm7m3r in this example) involves specifying replacement values for the fields you want to update. You can update multiple fields in the same request. This example updates the description and the licence of the dataset.

See steps involved

curl -X PATCH "https://api.mendeley.com/datasets/drafts/b7nzjm7m3r"
	-H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-draft-dataset.1+json"
	-H "Content-Type: application/vnd.mendeley-dataset-patch.1+json"
	-d '{"description":"A dataset created via the Mendeley API.", "data_licence":{"id":"126f78a3-08e2-42f2-a226-db28838adc93"}}'

Adding files

Adding files is a special case of editing a draft. Mendeley has a separate API for uploading files. You POST the file’s binary content and receive an identifier that can be used to attach the file to the draft.

See steps involved

To upload a file (my-data.xls in this example), you should POST the file contents along with its Content-Type:

curl -X POST "https://api.mendeley.com/file_content"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-content-ticket.1+json"
	-H "Content-Type: application/vnd.ms-excel" --data-binary @my-data.xls

Make note of the id in the JSON this returns. You will need this to add the file to the dataset. In this example we’ve assumed the id is cbc3b164-6743-4596-99a1-9644dc714b60:

curl -X PATCH "https://api.mendeley.com/datasets/drafts/b7nzjm7m3r"
	-H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-draft-dataset.1+json"
	-H "Content-Type: application/vnd.mendeley-dataset-patch.1+json"
	-d '{"files":[{"filename":"my-data.xls","description":"My data","content_details":{"id":"cbc3b164-6743-4596-99a1-9644dc714b60"}}]}'

files is an array, so you can attach multiple files to the dataset in a single PATCH operation.

Sharing a draft dataset

Draft datasets are private and can only be accessed by their creator. The creator can allow other people to view (but not edit) the draft by giving them the value stored in the access_code field.

See steps involved

You can retrieve someone else’s draft (3dyfw2py9d in this example) using their access code (cf78b5ea-ea5d-4d55-9901-2163ccf958ce in this example).

curl -X GET "https://api.mendeley.com/datasets/drafts/3dyfw2py9d?access_code=cf78b5ea-ea5d-4d55-9901-2163ccf958ce"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-draft-dataset.1+json"

When the draft is published, the new draft version will have a different access code.

Publishing a dataset

There is an API call that allows you to publish a draft dataset (b7nzjm7m3r in this example).

See steps involved

curl -X POST "https://api.mendeley.com/datasets/drafts/b7nzjm7m3r"
	-H "Authorization: Bearer $TOKEN"
	-H "Accept: application/vnd.mendeley-content-ticket.1+json"

After publishing, you can continue to edit your draft, but it will now have a higher version number, a different provisional DOI and a new access code.

Several fields that are optional while editing a draft dataset are mandatory for publishing. If your dataset is not suitable for publishing you will receive an error response like this.


{
  "message": "This dataset has errors that prevent you publishing it",
  "field_errors": [
   {
	  "field": "description",
	  "message": "Dataset should have a description"
   },
   {
	  "field": "categories",
	  "message": "Dataset should have at least one category"
   },
   {
	  "field": "files",
	  "message": "Dataset should contain at least one file"
   }
  ]
}

Once the error for each listed field in the JSON has been resolved, you will be able to publish the draft.

Publishing data under embargo

Datasets can be published under embargo. This involves setting an embargo date on the draft. When the draft is published, it will be under embargo until the date you’ve specified, and only very limited information about it will be available (currently the name of the dataset, its DOI and the embargo date).

See steps involved

curl -X PATCH "https://api.mendeley.com/datasets/drafts/b7nzjm7m3r"
	-H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-draft-dataset.1+json"
	-H "Content-Type: application/vnd.mendeley-dataset-patch.1+json"
	-d '{"embargo_date":"2020-01-01T00:00:00Z"}'

To remove the embargo from a draft, set an embargo date in the past.

Datasets API Quick Start Guides

Retrieve the ids of published datasets

Retrieving a dataset by id

Avoiding multiple API calls

Searching for datasets linked to an article or a journal

Creating a new dataset

Editing a draft

Adding files

Sharing a draft dataset

Publishing a dataset

Publishing data under embargo