Queries and filtering

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

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; 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.nameIdentifierScheme: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)

The boolean operators AND, OR and NOT (case-sensitive) are also supported. When multiple operators are used together, use parentheses to combine them.

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.

ParameterDescription
page[size]results per per page
page[number]page number
sortsort results by a certain field
includeside-load associations

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:

$ 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:

FilterPossible valuesDescription
provider-id{provider-id}metadata associated with a specific DataCite provider (Direct Member, Consortium, or Consortium Organization)
client-id{client-id}metadata associated with a specific DataCite client (repository)
consortium-id{consortium-id}metadata associated with a specific DataCite consortium
resource-type-id{resource-type-id}metadata for a specific resourceTypeGeneral
person-id{person-id}metadata associated with a specific person's ORCID iD
registered{registered}metadata where year of DOI registration (registered in global handle server) is {year}
created{created}metadata where year of DOI creation (created in DataCite system) is {created}
schema-version{schema-version}metadata where schema version of the deposited metadata is {schema-version}

👍

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

Elasticsearch queries

The API supports Elasticsearch query string queries. The query structure follows the same structure as the elements in the JSON API. All of the elements that can be searched can be seen in the response below:

$ curl https://api.test.datacite.org/dois/10.70126/t70h-qt35?affiliation=true
{
  "id": "https://doi.org/10.70126/t70h-qt35",
  "doi": "10.70126/T70H-QT35",
  "url": "https://dataverse.scholarsportal.info/dataverse.xhtml",
  "types": {
    "ris": "COMP",
    "bibtex": "misc",
    "citeproc": "article",
    "schemaOrg": "SoftwareSourceCode",
    "resourceType": "XML",
    "resourceTypeGeneral": "Software"
  },
  "creators": [
    {
      "name": "Miller, Elizabeth",
      "nameType": "Personal",
      "givenName": "Elizabeth",
      "familyName": "Miller",
      "affiliation": [
        {
          "name": "DataCite",
          "affiliationIdentifier": "https://ror.org/04wxnsj81",
          "affiliationIdentifierScheme": "ROR"
        }
      ],
      "nameIdentifiers": [
        {
          "schemeUri": "https://orcid.org",
          "nameIdentifier": "https://orcid.org/0000-0001-5000-0007",
          "nameIdentifierScheme": "ORCID"
        }
      ]
    },
    {
      "name": "Ontario Ministry Of Natural Resources And Forestry",
      "nameType": "Organizational",
      "affiliation": [],
      "nameIdentifiers": []
    },
    {
      "name": "Université Du Québec à Montréal",
      "nameType": "Organizational",
      "affiliation": [],
      "nameIdentifiers": []
    }
  ],
  "titles": [
    {
      "lang": "en-US",
      "title": "Full DataCite XML Example"
    },
    {
      "lang": "en-US",
      "title": "Demonstration of DataCite Properties.",
      "titleType": "Subtitle"
    }
  ],
  "publisher": "National Research Council of Canada",
  "container": {},
  "subjects": [
    {
      "lang": "en-US",
      "subject": "000 computer science",
      "schemeUri": "http://dewey.info/",
      "subjectScheme": "dewey"
    }
  ],
  "contributors": [
    {
      "name": "Starr, Joan",
      "givenName": "Joan",
      "familyName": "Starr",
      "affiliation": [
        {
          "name": "California Digital Library",
          "affiliationIdentifier": "https://ror.org/03yrm5c26",
          "affiliationIdentifierScheme": "ROR"
        }
      ],
      "contributorType": "ProjectLeader",
      "nameIdentifiers": [
        {
          "schemeUri": "https://orcid.org",
          "nameIdentifier": "https://orcid.org/0000-0002-7285-027X",
          "nameIdentifierScheme": "ORCID"
        }
      ]
    },
    {
      "name": "International Joint Commission",
      "affiliation": [],
      "contributorType": "Sponsor",
      "nameIdentifiers": []
    },
    {
      "name": "United States Geological Survey",
      "affiliation": [],
      "contributorType": "Producer",
      "nameIdentifiers": []
    }
  ],
  "dates": [
    {
      "date": "2017-09-13",
      "dateType": "Updated",
      "dateInformation": "Updated with 4.3 properties"
    },
    {
      "date": "2014",
      "dateType": "Issued"
    }
  ],
  "publicationYear": 2014,
  "language": "en-US",
  "identifiers": [],
  "sizes": [
    "4 kB"
  ],
  "formats": [
    "application/xml"
  ],
  "version": "4.3",
  "rightsList": [
    {
      "lang": "en-US",
      "rightsUri": "http://creativecommons.org/publicdomain/zero/1.0"
    }
  ],
  "descriptions": [
    {
      "lang": "en-US",
      "description": "XML example of all DataCite Metadata Schema v4.3 properties.",
      "descriptionType": "Abstract"
    }
  ],
  "geoLocations": [
    {
      "geoLocationBox": {
        "eastBoundLongitude": "-68.211",
        "northBoundLatitude": "42.893",
        "southBoundLatitude": "41.090",
        "westBoundLongitude": "-71.032"
      },
      "geoLocationPlace": "Atlantic Ocean",
      "geoLocationPoint": {
        "pointLatitude": "31.233",
        "pointLongitude": "-67.302"
      },
      "geoLocationPolygon": [
        {
          "polygonPoint": {
            "pointLatitude": "41.991",
            "pointLongitude": "-71.032"
          }
        },
        {
          "polygonPoint": {
            "pointLatitude": "42.893",
            "pointLongitude": "-69.622"
          }
        },
        {
          "polygonPoint": {
            "pointLatitude": "41.991",
            "pointLongitude": "-68.211"
          }
        },
        {
          "polygonPoint": {
            "pointLatitude": "41.090",
            "pointLongitude": "-69.622"
          }
        },
        {
          "polygonPoint": {
            "pointLatitude": "41.991",
            "pointLongitude": "-71.032"
          }
        }
      ]
    }
  ],
  "fundingReferences": [
    {
      "awardTitle": "Full DataCite XML Example",
      "funderName": "National Science Foundation",
      "awardNumber": "CBET-106",
      "funderIdentifier": "https://doi.org/10.13039/100000001",
      "funderIdentifierType": "Crossref Funder ID"
    }
  ],
  "relatedIdentifiers": [
    {
      "schemeUri": "https://github.com/citation-style-language/schema/raw/master/csl-data.json",
      "relationType": "HasMetadata",
      "relatedIdentifier": "https://data.datacite.org/application/citeproc+json/10.5072/example-full",
      "relatedIdentifierType": "URL",
      "relatedMetadataScheme": "citeproc+json"
    },
    {
      "relationType": "IsReviewedBy",
      "relatedIdentifier": "arXiv:0706.0001",
      "resourceTypeGeneral": "Text",
      "relatedIdentifierType": "arXiv"
    }
  ],
  "schemaVersion": "http://datacite.org/schema/kernel-4",
  "providerId": "datacite",
  "clientId": "datacite.mary",
  "agency": "DataCite",
  "state": "findable"
}

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 to 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 queries. 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:"CrowdoMeter Tweets"

5. Boolean operators (e.g. AND OR + -)

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.

$ 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:"Fenner, Martin" AND relatedIdentifiers.relationType:HasPart