openapi: 3.1.0
info:
title: Dryad datasets search API
description: "Dryad's REST API allows detailed interaction and programmatic interfacing with Dryad contents. The most common case is to use GET requests to retrieve information about datasets, versions, and files.\n\nWhen using the API, any DOI included must be <a href=\"https://www.w3schools.com/tags/ref_urlencode.ASP\" target=\"blank\">URL-encoded<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a> to ensure correct processing. Anonymous users of the API are limited to 30 requests per minute, and are not allowed to download data files. \n\nExamples:\n\n- [List datasets](https://datadryad.org/api/v2/datasets)\n- [Search for datasets](https://datadryad.org/api/v2/search?q=carbon)\n- [Get information about a dataset](https://datadryad.org/api/v2/datasets/doi%3A10.5061%2Fdryad.j1fd7)\n- [List versions of a dataset](https://datadryad.org/api/v2/datasets/doi%3A10.5061%2Fdryad.j1fd7/versions)\n- [List files in a version](https://datadryad.org/api/v2/versions/26724/files)\n\nDetailed documentation:\n\n- For details on all of our REST API operations, click the links in the menu on this page.\n- [Search API](https://github.com/datadryad/dryad-app/blob/main/documentation/apis/search.md)\n- [Submission API](https://github.com/datadryad/dryad-app/blob/main/documentation/apis/submission.md)\n\n## API accounts \n\nTo access more powerful features, an API account is required. API accounts allow users to:\n\n- Access the API at higher rates (authenticated users may make up to 240 requests per minute)\n- Download data files\n- Access datasets that are not yet public, but are associated with the account's community (institution, journal, etc.)\n- Update datasets associated with the account's community\n\nSee the <a href=\"https://github.com/datadryad/dryad-app/blob/main/documentation/apis/api_accounts.md\" target=\"blank\">API accounts document<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a> for more information on requesting an API account and using it to access datasets.\n\n\n## Submission\n\nThe Submission API is used by organizations that partner closely with Dryad, and use systems to create dataset submissions directly. Please contact us if you are [interested in partnering with Dryad](/contact#get-involved), and setting up an API account for submission.\n\nThe <a href=\"https://github.com/datadryad/dryad-app/blob/main/documentation/apis/submission.md\" target=\"blank\">API submission examples document<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a> gives concrete examples of submission through the Dryad API.\n\n\n### Dryad sandbox\n\n<a href=\"https://sandbox.datadryad.org/\" target=\"blank\">Dryad's sandbox server<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a> allows users to experiment with data submission and the Dryad API, without worrying about the effects on \"real\" data. Anyone may create an account on the sandbox server for testing purposes. When creating an account, keep in mind that Dryad's sandbox relies on the <a href=\"https://sandbox.orcid.org/\" target=\"_blank\">sandbox version of ORCID<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a>, which allows you to make test ORCID accounts. Sandbox ORCID IDs should be used in the Dryad sandbox, while use of Dryad's production system requires a real ORCID ID.\n"
version: 2.1.0
servers:
- url: https://datadryad.org/api/v2
description: Main Dryad server
- url: https://sandbox.datadryad.org/api/v2
description: Sandbox server, for testing new features.
tags:
- name: search
description: Searching datasets
paths:
/search:
get:
summary: Search publicly-available datasets
tags:
- search
description: Search the published Dryad datasets. Query all fields, or look for terms in specific metadata fields of the dataset.
parameters:
- in: query
name: q
schema:
type: string
description: A list of terms to be searched. If multiple terms are supplied, matches will only be returned for items that contain all terms. Terms may include an `*` at the end to indicate a wildcard. A term may be negated to indicate that it should *not* be present in the results (e.g., `cat -fish`). Use quotation marks to search for an exact phrase.
- in: query
name: subject
schema:
type: string
description: Search for a dataset by subject keyword.
- in: query
name: orcid
schema:
type: string
description: Search for authors using author [ORCIDs](https://orcid.org/). If multiple, separate with a space.
- in: query
name: author
schema:
type: string
description: Search for authors by name.
- in: query
name: affiliation
schema:
type: string
description: A ROR identifier for an institutional affiliation that must be present in the list of dataset authors. The identifier should be in the full "https" format and should be URL-encoded, e.g., `https%3A%2F%2Fror.org%2F00x6h5n95`.
- in: query
name: facility
schema:
type: string
description: A ROR identifier for the dataset research facility. The identifier should be in the full "https" format and should be URL-encoded, e.g., `https%3A%2F%2Fror.org%2F00x6h5n95`.
- in: query
name: funder
schema:
type: string
description: A ROR identifier for a dataset funder. The identifier should be in the full "https" format and should be URL-encoded, e.g., `https%3A%2F%2Fror.org%2F00x6h5n95`.
- in: query
name: org
schema:
type: string
description: A ROR identifier for a dataset funder, affiliation, or research facility. The identifier should be in the full "https" format and should be URL-encoded, e.g., `https%3A%2F%2Fror.org%2F00x6h5n95`.
- in: query
name: tenant
schema:
type: string
description: The abbreviation for a partner organization in Dryad. This will automatically search all organizations associated with the given tenant.
- in: query
name: award
schema:
type: string
description: An award or grant number associated with the dataset.
- in: query
name: journalISSN
schema:
type: string
description: The journal ISSN.
- in: query
name: relatedId
schema:
type: string
description: Any related work ID associated with the dataset, including manuscript numbers and PubMed IDs.
- in: query
name: publishedSince
schema:
type: string
description: A date or timestamp for limiting results. Datasets will only be returned that have been published since the given date/time. The date must be specified in ISO 8601 format (`2020-10-08`). If including a time, the time must be specified in ISO 8601 format, and the time zone must be set to UTC, e.g., `2020-10-08T10:24:53Z`.
- in: query
name: publishedBefore
schema:
type: string
description: A date or timestamp for limiting results. Datasets will only be returned that have been published before the given date/time. The date must be specified in ISO 8601 format (`2020-10-08`). If including a time, the time must be specified in ISO 8601 format, and the time zone must be set to UTC, e.g., `2020-10-08T10:24:53Z`.
- in: query
name: relatedWorkIdentifier
schema:
type: string
description: A DOI or other URL that links a dataset to a related work. It allows `*` as a wildcard at the beginning and/or end of the value.
- in: query
name: relatedWorkRelationship
schema:
type: string
description: The type of relationship expressed by a related work.
- in: query
name: modifiedSince
schema:
type: string
description: A date or timestamp for limiting results. Datasets will only be returned that have been modified since the given date/time. The date must be specified in ISO 8601 format (`2020-10-08`). If including a time, the time must be specified in ISO 8601 format, and the time zone must be set to UTC, e.g., `2020-10-08T10:24:53Z`.
- in: query
name: modifiedBefore
schema:
type: string
description: A date or timestamp for limiting results. Datasets will only be returned that have been modified before the given date/time. The date must be specified in ISO 8601 format (`2020-10-08`). If including a time, the time must be specified in ISO 8601 format, and the time zone must be set to UTC, e.g., `2020-10-08T10:24:53Z`.
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
responses:
'200':
description: A list of datasets.
content:
application/json:
schema:
$ref: '#/components/schemas/datasets'
examples:
success:
$ref: api/v2/docs/examples/datasets.json
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Dryad encountered an error parsing the query options for the search. The most likely cause of this problem is an improperly-formatted timestamp for the `modifiedSince` parameter.
components:
parameters:
per_page:
in: query
name: per_page
schema:
type: integer
description: Number of results to return on each page. Defaults to 20. Maximum allowed is 100.
page:
in: query
name: page
schema:
type: integer
description: Which page of results to view. Defaults to page 1.
schemas:
embedded_datasets:
type: object
properties:
_embedded:
type: object
properties:
stash:datasets:
type: array
items:
$ref: '#/components/schemas/dataset'
geolocationBox:
properties:
swLongitude:
description: The longitude of the southwest corner of the box.
type: number
swLatitude:
description: The latitude of the southwest corner of the box.
type: number
neLongitude:
description: The longitude of the northeast corner of the box.
type: number
neLatitude:
description: The latitude of the northeast corner of the box.
type: number
hal_page_links:
properties:
first:
$ref: '#/components/schemas/hal_link'
last:
$ref: '#/components/schemas/hal_link'
prev:
$ref: '#/components/schemas/hal_link'
next:
$ref: '#/components/schemas/hal_link'
relatedWork:
properties:
relationship:
format: string
enum:
- article
- dataset
- preprint
- software
- supplemental_information
- primary_article
- data_management_plan
identifierType:
type: string
identifier:
type: string
hal_paged_response:
allOf:
- properties:
_links:
allOf:
- $ref: '#/components/schemas/hal_self_link'
- $ref: '#/components/schemas/hal_page_links'
- $ref: '#/components/schemas/paging_counts'
paging_counts:
properties:
count:
type: integer
total:
type: integer
dataset_links:
properties:
_links:
allOf:
- $ref: '#/components/schemas/hal_self_link'
- $ref: '#/components/schemas/hal_dataset_links'
hal_version_links:
properties:
stash:dataset:
$ref: '#/components/schemas/hal_link'
stash:files:
$ref: '#/components/schemas/hal_link'
stash:download:
$ref: '#/components/schemas/hal_link'
curies:
type: array
items:
$ref: '#/components/schemas/hal_curie'
funder:
properties:
organization:
type: string
identifier:
type: string
description: The organization identifier, for example a ROR ID.
example: https://ror.org/00x6h5n95
identifierType:
description: Type of identifier — ror, isni, grid, crossref_funder_id or other.
type: string
example: ror
awardNumber:
type: string
awardDescription:
description: Usually used for the program or the division of the award.
type: string
order:
type: integer
hal_link:
type: object
properties:
href:
type: string
format: uri
required:
- href
Error:
type: object
properties:
error:
type: string
geolocationPoint:
type: object
properties:
latitude:
description: The latitude of the point.
type: number
longitude:
description: The longitude of the point.
type: number
dataset:
allOf:
- properties:
identifier:
type: string
id:
type: integer
storageSize:
type: integer
relatedPublicationISSN:
type: string
- $ref: '#/components/schemas/version'
- $ref: '#/components/schemas/dataset_links'
- properties:
metrics:
type: object
properties:
views:
type: integer
downloads:
type: integer
citations:
type: integer
license:
type: string
description: The license of the dataset
dc_metadata:
type: object
properties:
title:
type: string
authors:
type: array
items:
$ref: '#/components/schemas/author'
abstract:
type: string
description: An abstract introducing the dataset.
funders:
type: array
items:
$ref: '#/components/schemas/funder'
keywords:
type: array
items:
type: string
fieldOfScience:
type: string
description: A term from the FOS (Fields of Science and Technology) controlled vocabulary. The main category of the dataset.
hsiStatement:
type: string
description: A statement explaining the de-identification of any human subject data in the dataset.
methods:
type: string
description: The methods by which the data was produced. Not required for publication.
usageNotes:
type: string
description: Usage notes for the dataset (Deprecated; It is preferred for this content to appear in the README file for the dataset). If the dataset has been retracted, the retraction statement will appear here.
locations:
type: array
items:
$ref: '#/components/schemas/geolocation'
relatedWorks:
type: array
items:
$ref: '#/components/schemas/relatedWork'
required:
- title
- authors
- abstract
version:
allOf:
- $ref: '#/components/schemas/version_links'
- $ref: '#/components/schemas/dc_metadata'
- properties:
versionNumber:
type: integer
versionStatus:
type: string
enum:
- in_progress
- processing
- submitted
description: Internal processing status of files.
curationStatus:
type: string
enum:
- In progress
- Processing
- Queued for curation
- Private for Peer Review
- Awaiting payment
- Curation
- Action required
- Withdrawn
- Embargoed
- Published
description: Status of the submission in the curation workflow.
versionChanges:
type: string
enum:
- files_changed
- metadata_changed
publicationDate:
type: string
lastModificationDate:
type: string
visibility:
type: string
description: Whether or not this version is publicly visible.
geolocation:
properties:
place:
description: A place name.
type: string
box:
$ref: '#/components/schemas/geolocationBox'
description: A bounding box.
point:
$ref: '#/components/schemas/geolocationPoint'
description: A coordinate point.
hal_self_link:
type: object
properties:
self:
$ref: '#/components/schemas/hal_link'
hal_curie:
type: object
properties:
name:
type: string
href:
type: string
format: uri
templated:
type: boolean
required:
- name
- href
- templated
hal_dataset_links:
properties:
stash:versions:
$ref: '#/components/schemas/hal_link'
stash:version:
$ref: '#/components/schemas/hal_link'
stash:download:
$ref: '#/components/schemas/hal_link'
curies:
type: array
items:
$ref: '#/components/schemas/hal_curie'
version_links:
properties:
_links:
allOf:
- $ref: '#/components/schemas/hal_self_link'
- $ref: '#/components/schemas/hal_version_links'
author:
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
affiliation:
type: string
affiliationROR:
type: string
description: Preferred identifier for the author affiliation.
affiliations:
type: array
items:
name: string
ror_id: string
affiliationISNI:
type: string
orcid:
type: string
order:
type: integer
datasets:
allOf:
- $ref: '#/components/schemas/hal_paged_response'
- $ref: '#/components/schemas/embedded_datasets'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT