OpenCitations Citations API
Operations for retrieving citation metadata and counts
OpenAPI Specification
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