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.
| Parameter | Description |
|---|---|
page[size] | results per per page |
page[number] | page number |
sort | sort results by a certain field |
include | side-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:
| Filter | Possible values | Description |
|---|---|---|
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
Updated 4 months ago