Making Queries

The API supports the use of queries, which return lists as responses. The previous section of this guide (Retrieving a list of DOIs) dealt with the basics of list results. This section will cover making queries and filtering the response lists.

$ curl https://api.test.datacite.org/dois?query=climate%20change

The response is a list of all the DOI records that contain the phrases climate or change in their metadata. The REST API uses Elasticsearch Query String Queries.

The query string is parsed into a series of terms and operators. A term can be a single word — quick or brown — or a phrase, surrounded by double quotes — "quick brown" — which searches for all the words in the phrase, in the same order.

The specifics of Query String Queries are discussed at the link provided above, but a summary is given below.

Field names

Queries by default search all fields, but a specific field can be provided in the query, e.g.

$ curl https://api.test.datacite.org/dois?query=publicationYear:2016

For nested fields use the same format as in the REST API response, e.g.

$ curl https://api.test.datacite.org/dois?query=creators.nameIdentifiers.nameIdentifierType:ORCID

Wildcards

Wildcards are supported, e.g.

$ curl https://api.test.datacite.org/dois?query=creators.nameIdentifiers.nameIdentifier:*
$ curl https://api.test.datacite.org/dois?query=creators.familyName:mil*

Boolean operators

By default, all terms are optional, as long as one term matches. Use + or - to specify terms that have to match or not match, respectively. For example

$ curl https://api.test.datacite.org/dois?query=titles.title:climate%20+change

Additional parameters can be used to query, filter and control the results returned by the DataCite API. They can be passed as normal URI parameters or as JSON in the body of the request.

For example, to list one single work using the previously specified query, you would add a page[size] parameter with a value of 1, like so:

#GET dois?query=
$ curl https://api.test.datacite.org/dois?query=climate+change&page[size]=1

Filtering List Responses

The API supports filters that allow you to narrow queries. All filter results are lists. For example, if you wish to filter results by client to find everything that is managed by the client dryad.dryad (Dryad Digital Repository), you would do the following:

$ curl https://api.test.datacite.org/dois?client-id=dryad.dryad

The following filters are supported:

👍

What's in the response?

Query results are returned as a list of DOI records in JSON format, as described in Retrieving a list of DOIs.

Note: Affiliation identifiers (supported in Metadata Schema 4.3+) are not included in REST API responses by default. To include affiliation identifier details, add &affiliation=true to your queries. See our FAQ for more information

The REST API also supports retrieving a random sample of results. The next section of this guide will cover sampling (see Retrieving a random sample of DOIs).