Dryad Search API

openapi: 3.2.0
info:
  title: Dryad Search API
  description: Dryad's REST API allows detailed interaction and programmatic interfacing with Dryad contents.
  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.
      operationId: getSearch
      x-operation-id-source: derived
components:
  schemas:
    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.
    paging_counts:
      properties:
        count:
          type: integer
        total:
          type: integer
    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
    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
    Error:
      type: object
      properties:
        error:
          type: string
    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
    hal_self_link:
      type: object
      properties:
        self:
          $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_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'
    geolocationPoint:
      type: object
      properties:
        latitude:
          description: The latitude of the point.
          type: number
        longitude:
          description: The longitude of the point.
          type: number
    version_links:
      properties:
        _links:
          allOf:
          - $ref: '#/components/schemas/hal_self_link'
          - $ref: '#/components/schemas/hal_version_links'
    embedded_datasets:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            stash:datasets:
              type: array
              items:
                $ref: '#/components/schemas/dataset'
    hal_paged_response:
      allOf:
      - properties:
          _links:
            allOf:
            - $ref: '#/components/schemas/hal_self_link'
            - $ref: '#/components/schemas/hal_page_links'
      - $ref: '#/components/schemas/paging_counts'
    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.
    hal_link:
      type: object
      properties:
        href:
          type: string
          format: uri
      required:
      - href
    datasets:
      allOf:
      - $ref: '#/components/schemas/hal_paged_response'
      - $ref: '#/components/schemas/embedded_datasets'
    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'
    hal_curie:
      type: object
      properties:
        name:
          type: string
        href:
          type: string
          format: uri
        templated:
          type: boolean
      required:
      - name
      - href
      - templated
    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
    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_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'
    dataset_links:
      properties:
        _links:
          allOf:
          - $ref: '#/components/schemas/hal_self_link'
          - $ref: '#/components/schemas/hal_dataset_links'
  parameters:
    page:
      in: query
      name: page
      schema:
        type: integer
      description: Which page of results to view. Defaults to page 1.
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT