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:

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.

Exact match searches

Enclose the query in quotations " " to search for exact matches only. For example:

curl "https://api.datacite.org/dois?query=creators.affiliation.name:%22Oklahoma%20State%20University%22"

📘

Exact match searches with " " don't work with wildcard searches

To search using a * or ? wildcard before or after an exact match search, the spaces must be escaped with \ and the quotation marks must be excluded:

https://api.datacite.org/dois?query=creators.affiliation.name:Oklahoma\ State\ University*

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. Exact match searches

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:

Additional parameters

Additional parameters can be used to control the results returned by the DataCite REST API.

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.

📘

Retrieving the full metadata record

To retrieve the full metadata record with the REST API, include both the affiliation parameter &affiliation=trueand publisher parameter&publisher=truein your requests:

https://api.datacite.org/dois?client-id=datacite.datacite&affiliation=true&publisher=true

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.

📘

Retrieving the XML metadata with the REST API

To retrieve the XML version of the metadata in your response, include the &detail=true parameter in your requests:

https://api.datacite.org/dois?client-id=datacite.datacite&detail=true

It is also possible to specify which fields are returned using the fields[dois] parameter.

📘

Specify which fields to retrieve in the response

For example, to return only titles and subjects, includefields[dois]=titles,subjects in your request:

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).