openapi: 3.0.3
info:
  title: OpenCitations Index REST Authors Citations API
  description: 'REST API for accessing the data stored in the OpenCitations Index. Provides operations to retrieve citation data for references to other works appearing in a particular bibliographic entity, or citation data for references in other works to a particular bibliographic entity, given the identifier of a bibliographic entity, or to retrieve citation data about a particular citation identified by means of its Open Citation Identifier (OCI).

    All operations return either a JSON document (default) or a CSV document according to the mimetype specified in the Accept header of the request.

    API calls are rate-limited to 180 requests/minute per IP address. For large-scale retrieval use the database dumps at download.opencitations.net.

    '
  version: 2.2.0
  contact:
    name: OpenCitations
    email: contact@opencitations.net
    url: https://opencitations.net
  license:
    name: Creative Commons Attribution 4.0 International
    url: https://creativecommons.org/licenses/by/4.0/legalcode
  x-api-created: '2025-04-15'
servers:
- url: https://api.opencitations.net/index/v2
  description: OpenCitations Index API v2
security:
- accessToken: []
- {}
tags:
- name: Citations
  description: Operations for retrieving citation metadata and counts
paths:
  /citation/{oci}:
    get:
      summary: Get citation by OCI
      operationId: getCitationByOCI
      description: 'Retrieves the citation metadata for the citation identified by the input Open Citation Identifier (OCI).

        The Open Citation Identifier is a globally unique persistent identifier for bibliographic citations, consisting of two numbers separated by a dash (without the "oci:" prefix).

        Fields returned: - oci: the Open Citation Identifier of the citation - citing: the PIDs of the citing entity - cited: the PIDs of the cited entity - creation: the creation date of the citation (ISO 8601 YYYY-MM-DD) - timespan: interval between publication dates (XSD duration PnYnMnD) - journal_sc: whether the citation is a journal self-citation (yes/no) - author_sc: whether the citation is an author self-citation (yes/no)

        '
      tags:
      - Citations
      parameters:
      - name: oci
        in: path
        required: true
        description: 'The dash-separated OCI number pair (without "oci:" prefix). Example: 06101801781-06180334099

          '
        schema:
          type: string
          pattern: ^[0-9]+-[0-9]+$
          example: 06101801781-06180334099
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Citation metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Citation'
              example:
              - oci: 06101801781-06180334099
                citing: omid:br/06101801781 doi:10.7717/peerj-cs.421 pmid:33817056
                cited: omid:br/06180334099 doi:10.1108/jd-12-2013-0166
                creation: '2021-03-10'
                timespan: P6Y0M1D
                journal_sc: 'no'
                author_sc: 'no'
            text/csv:
              schema:
                type: string
        '404':
          description: Citation not found
  /citation-count/{id}:
    get:
      summary: Get incoming citation count
      operationId: getCitationCount
      description: 'Retrieves the number of incoming citations to the bibliographic entity identified by the input PID (DOI, PMID, or OMID).

        '
      tags:
      - Citations
      parameters:
      - name: id
        in: path
        required: true
        description: 'PID of the bibliographic entity. Must be prefixed with identifier type: doi:, pmid:, or omid:

          '
        schema:
          type: string
          pattern: ^(omid|doi|pmid):.+
          example: doi:10.1108/jd-12-2013-0166
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Incoming citation count
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Count'
              example:
              - count: '34'
            text/csv:
              schema:
                type: string
  /venue-citation-count/{id}:
    get:
      summary: Get venue incoming citation count
      operationId: getVenueCitationCount
      description: 'Retrieves the number of incoming citations to all bibliographic entities published in a specific journal identified by the input ISSN.

        '
      tags:
      - Citations
      parameters:
      - name: id
        in: path
        required: true
        description: ISSN of the journal, prefixed with "issn:"
        schema:
          type: string
          pattern: ^issn:.+
          example: issn:0138-9130
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Total incoming citation count for venue
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Count'
              example:
              - count: '64352'
            text/csv:
              schema:
                type: string
  /citations/{id}:
    get:
      summary: Get incoming citations
      operationId: getCitations
      description: 'Retrieves citation data for all references appearing in the reference lists of other citing works to the bibliographic entity identified by the input PID (DOI, PMID, or OMID). These constitute the incoming citations of the identified bibliographic entity.

        Fields returned: oci, citing, cited, creation, timespan, journal_sc, author_sc.

        '
      tags:
      - Citations
      parameters:
      - name: id
        in: path
        required: true
        description: 'PID of the bibliographic entity. Must be prefixed with identifier type: doi:, pmid:, or omid:

          '
        schema:
          type: string
          pattern: ^(omid|doi|pmid):.+
          example: doi:10.1108/jd-12-2013-0166
      - $ref: '#/components/parameters/require'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/json'
      responses:
        '200':
          description: Incoming citations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Citation'
            text/csv:
              schema:
                type: string
components:
  schemas:
    Count:
      type: object
      description: Citation or reference count result
      properties:
        count:
          type: string
          description: Number of citations or references
          example: '34'
    Citation:
      type: object
      description: Citation metadata record
      properties:
        oci:
          type: string
          description: Open Citation Identifier (OCI) of the citation
          example: 06101801781-06180334099
        citing:
          type: string
          description: Space-separated PIDs of the citing entity (prefixed with index name)
          example: omid:br/06101801781 doi:10.7717/peerj-cs.421 pmid:33817056
        cited:
          type: string
          description: Space-separated PIDs of the cited entity (prefixed with index name)
          example: omid:br/06180334099 doi:10.1108/jd-12-2013-0166
        creation:
          type: string
          format: date
          description: Creation date of the citation (ISO 8601 YYYY-MM-DD)
          example: '2021-03-10'
        timespan:
          type: string
          description: Interval between publication dates in XSD duration format (PnYnMnD)
          example: P6Y0M1D
        journal_sc:
          type: string
          enum:
          - true
          - false
          description: Whether the citation is a journal self-citation
          example: 'no'
        author_sc:
          type: string
          enum:
          - true
          - false
          description: Whether the citation is an author self-citation
          example: 'no'
  parameters:
    filter:
      name: filter
      in: query
      required: false
      description: 'Applies conditional filtering. Supports regex or operators (=, <, >). Format: field:operator:value. Example: date:>2015

        '
      schema:
        type: string
        example: date:>2015
    format:
      name: format
      in: query
      required: false
      description: Output format. Accepts "csv" or "json" (default).
      schema:
        type: string
        enum:
        - json
        - csv
        default: json
    sort:
      name: sort
      in: query
      required: false
      description: 'Orders results by field in ascending or descending order. Format: asc(field) or desc(field).

        '
      schema:
        type: string
        example: desc(date)
    json:
      name: json
      in: query
      required: false
      description: 'Transforms JSON data structure. Supports array splitting or dict conversion.

        '
      schema:
        type: string
    require:
      name: require
      in: query
      required: false
      description: Removes rows with empty values in the specified field
      schema:
        type: string
        example: doi
  securitySchemes:
    accessToken:
      type: apiKey
      in: header
      name: authorization
      description: 'OpenCitations Access Token obtained from https://opencitations.net/accesstoken. Recommended for application/code usage to ensure stable access.

        '
externalDocs:
  description: OpenCitations Index API Documentation
  url: https://api.opencitations.net/index/v2