Queries and filtering

When retrieving a list of DOIs, the REST API supports several parameters that can be used to refine, sort, and change the presentation of the results. This guide provides more detail on the available options.

Applying filter parameters

The API supports filter parameters that refine the list of results.

This includes the following frequently used filters:

Filter	Example values	Description
`provider-id`	`cern`	DOIs associated with a specific DataCite provider (Direct Member or Consortium Organization)
`client-id`	`cern.zenodo`	DOIs associated with a specific DataCite client (repository)
`consortium-id`	`dcan`	DOIs associated with a specific DataCite consortium
`resource-type-id`	`output-management-plan`	DOIs that use a specific resourceTypeGeneral
`prefix`	`10.5061`	DOIs with a specific prefix
`registered`	`2016`	DOIs with a specific year of DOI registration (registered in global handle server)
`created`	`2020`	DOIs with a specific year of DOI creation (created in DataCite system)
`schema-version`	`4`	DOIs using a specific schema version for the associated metadata

For example, this request retrieves all DOIs registered by a specific Repository account:

curl "https://api.datacite.org/dois?client-id=datacite.datacite"

For a full list of parameters, please see the API Reference.

Using the "query" parameter

You can search DOI metadata using the “query” parameter. The REST API uses OpenSearch query string syntax. This guide contains selected examples to get you started with querying DataCite DOI metadata.

Building a query string

Metadata field names

Nested fields use the same structure as in the "attributes" section of the REST API response for a DOI metadata record. You can also refer to the DataCite XML to JSON mapping for a full list of how DataCite metadata is represented in JSON.

creators
- creators.name
- creators.lang
- creators.nameType
- creators.givenName
- creators.familyName
- creators.nameIdentifiers
  - creators.nameIdentifiers.nameIdentifier
  - creators.nameIdentifiers.nameIdentifierScheme
  - creators.nameIdentifiers.schemeUri
- creators.affiliation
  - creators.affiliation.name
  - creators.affiliation.affiliationIdentifier
  - creators.affiliation.affiliationIdentifierScheme
  - creators.affiliation.schemeUri
titles
- titles.title
- titles.lang
- titles.titleType
publisher
- publisher.name
- publisher.publisherIdentifier
- publisher.publisherIdentifierScheme
- publisher.schemeUri
- publisher.lang
publicationYear
subjects
- subjects.subject
- subjects.subjectScheme
- subjects.schemeUri
- subjects.valueUri
- subjects.classificationCode
contributors
- contributors.contributorType
- contributors.name
- contributors.lang
- contributors.nameType
- contributors.givenName
- contributors.familyName
- contributors.nameIdentifiers
  - contributors.nameIdentifiers.nameIdentifier
  - contributors.nameIdentifiers.nameIdentifierScheme
  - contributors.nameIdentifiers.schemeUri
- contributors.affiliation
  - contributors.affiliation.name
  - contributors.affiliation.affiliationIdentifier
  - contributors.affiliation.affiliationIdentifierScheme
  - contributors.affiliation.schemeUri
dates
- dates.date
- dates.dateType
- dates.dateInformation
language
types
- types.resourceType
- types.resourceTypeGeneral
alternateIdentifiers (or identifiers)
- alternateIdentifiers.alternateIdentifier (or identifiers.identifier)
- alternateIdentifiers.alternateIdentifierType (or identifiers.identifierType)
relatedIdentifiers
- relatedIdentifiers.relatedIdentifier
- relatedIdentifiers.relatedIdentifierType
- relatedIdentifiers.relationType
- relatedIdentifiers.relatedMetadataScheme
- relatedIdentifiers.schemeUri
- relatedIdentifiers.schemeType
- relatedIdentifiers.resourceTypeGeneral
sizes
formats
version
rightsList
- rightsList.rights
- rightsList.lang
- rightsList.rightsUri
- rightsList.rightsIdentifier
- rightsList.rightsIdentifierScheme
- rightsList.schemeUri
descriptions
- descriptions.description
- descriptions.lang
- descriptions.descriptionType
geoLocations
- geoLocations.geoLocationPlace
fundingReferences
- fundingReferences.funderName
- fundingReferences.funderIdentifier
- fundingReferences.funderIdentifierType
- fundingReferences.schemeUri
- fundingReferences.awardNumber
- fundingReferences.awardUri
- fundingReferences.awardTitle
relatedItems
- relatedItems.relatedItemType
- relatedItems.relationType
- relatedItems.relatedItemIdentifier
  - relatedItems.relatedItemIdentifier.relatedItemIdentifier
  - relatedItems.relatedItemIdentifier.relatedItemIdentifierType
  - relatedItems.relatedItemIdentifier.relatedMetadataScheme
  - relatedItems.relatedItemIdentifier.schemeURI
  - relatedItems.relatedItemIdentifier.schemeType
- relatedItems.creators
  - relatedItems.creators.name
  - relatedItems.creators.nameType
  - relatedItems.creators.givenNamE
  - relatedItems.creators.familyName
- relatedItems.titles
  - relatedItems.titles.title
  - relatedItems.titles.lang
  - relatedItems.titles.titleType
- relatedItems.publicationYear
- relatedItems.volume
- relatedItems.issue
- relatedItems.number
- relatedItems.numberType
- relatedItems.firstPage
- relatedItems.lastPage
- relatedItems.publisher
- relatedItems.edition
- relatedItems.contributors
  - relatedItems.contributors.contributorType
  - relatedItems.contributors.name
  - relatedItems.contributors.nameType
  - relatedItems.contributors.givenName
  - relatedItems.contributors.familyName

A specific field can be provided in the query. For example:

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

Nested fields are joined by a .. For example:

curl "https://api.datacite.org/dois?query=creators.nameIdentifiers.nameIdentifierScheme:ORCID"

When a field is not specified, the query by default searches commonly queried fields (including title, creator name, creator nameIdentifier, publisher, description, subject, and relatedIdentifier).

curl "https://api.datacite.org/dois?query=climate"

Wildcards

The wildcards * and ? are supported, e.g.:

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

* matches zero or more characters and ? matches any single character.

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, to search for DOIs containing both "climate" and "change" in the title field:

curl "https://api.datacite.org/dois?query=titles.title:(climate%20+change)"

The boolean operators AND, OR and NOT (case-sensitive) are also supported.

When multiple operators are used together, use parentheses to combine them. For example:
(titles.title:(climate AND change) OR descriptions.description:(climate AND change)) AND (publicationYear:2023)

curl "https://api.datacite.org/dois?query=(titles.title:(climate%20AND%20change)%20OR%20descriptions.description:(climate%20AND%20change))%20AND%20(publicationYear:2023)"

Query examples

1. Publisher

Search for a specific publisher.

publisher:DataCite

curl "https://api.datacite.org/dois?query=publisher:DataCite"

2. DOI

Search for a specific DOI.

doi:10.11570/18.0006

curl "https://api.datacite.org/dois?query=doi:10.11570/18.0006"

3. Affiliation

Combine the parent and child elements to construct the search for an affiliation.

},
  "creators": [
    {
      "name": "Bloggs, Jane",
      "nameType": "Personal",
      "givenName": "Jane",
      "familyName": "Bloggs",
      "affiliation": [
          {
             "name": "DataCite",
             "schemeUri": "https://ror.org",
             "affiliationIdentifier": "https://ror.org/04wxnsj81",
             "affiliationIdentifierScheme": "ROR"
          }
      ],

curl "https://api.datacite.org/dois?affiliation=true&query=creators.affiliation.name:DataCite"

To include affiliation identifier details, add &affiliation=true to your requests. See our FAQ for more information.

4. Quotes

Search the exact string enclosed in the quotes.

titles.title:"CrowdoMeter Tweets"

curl "https://api.datacite.org/dois?query=titles.title:%22CrowdoMeter%20Tweets%22"

5. Boolean operators

Search using the "AND" boolean.

types.resourceTypeGeneral:Software AND types.resourceType:XML

curl "https://api.datacite.org/dois?query=types.resourceTypeGeneral:Software%20AND%20types.resourceType:XML"

Search using the "AND" and "OR" booleans.

publisher:DataCite AND types.resourceTypeGeneral:(Text OR Dataset)

curl "https://api.datacite.org/dois?query=publisher:DataCite%20AND%20types.resourceTypeGeneral:(Text%20OR%20Dataset)"

6. Wildcards

Search using a wildcard *.

subjects.subject:robot*

curl "https://api.datacite.org/dois?query=subjects.subject:robot*"

7. Longer queries

Combine more than one element to limit the search results. In this example, the creators and the relatedIdentifier properties are used to build the query.

creators.name:"Fenner, Martin" AND relatedIdentifiers.relationType:HasPart

creators:

"creators": [
    {
      "name": "Fenner, Martin",
      "nameType": "Personal",
      "givenName": "Martin",
      "familyName": "Fenner",
      "affiliation": [],
      "nameIdentifiers": [
        {
          "nameIdentifier": "https://orcid.org/0000-0003-1419-2405",
          "nameIdentifierScheme": "ORCID"
        }
      ]
    }
  ],

relatedIdentifiers:

"relatedIdentifiers": [
    {
      "relationType": "HasPart",
      "relatedIdentifier": "10.5438/6423",
      "relatedIdentifierType": "DOI"
    },

curl "https://api.datacite.org/dois?query=creators.name:%22Fenner,%20Martin%22%20AND%20relatedIdentifiers.relationType:HasPart"

Sorting results

The sort parameter is used to reorder the results. For example, this request retrieves all DOIs sorted by the updated date (from most to least recent):

curl "https://api.datacite.org/dois?sort=-updated"

The sort parameter accepts the following options:

Option	Description
name	DOI name alphabetical ascending
-name	DOI name alphabetical descending
created	created date ascending
-created	created date descending
updated	updated date ascending
-updated	updated date descending
published	published date ascending
-published	published date descending
view-count	viewCount ascending
-view-count	viewCount descending
download-count	downloadCount ascending
-download-count	downloadCount descending
citation-count	citationCount ascending
-citation-count	citationCount descending
title	first title alphabetical ascending
-title	first title alphabetical descending
relevance	relevance score descending

Additional parameters

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

Selecting which metadata fields to retrieve

Affiliation identifiers (supported in Metadata Schema 4.3+) and publisher identifiers (supported in Metadata Schema 4.5+) are not included in REST API responses by default. See our FAQ for more information.

To include affiliation identifier details, add &affiliation=true to your requests.
To include publisher identifier details, add &publisher=true to your requests.
To include additional attributes in a list of DOIs (prefix, suffix, viewsOverTime, citationsOverTime, provider, references, citations. parts, partOf, versions, versionOf, xml, alternateIdentifiers), add &detail=true to your requests.

It is also possible to specify which fields are returned using the fields[dois] parameter. For example, fields[dois]=titles,subjects will only return titles and subjects:

curl "https://api.datacite.org/dois?fields[dois]=titles,subjects"

Pagination

The page[number], page[size], and page[cursor] parameters are used for pagination. See the Pagination guide for more information.

Sampling

The REST API also supports retrieving a random sample of results with the random, sample, and sample-group parameters. The next section of this guide covers sampling (see Retrieving a random sample of DOIs).