The unifying REST API for all the OpenCitations Indexes

Version: Version 1.0.0 (2019-03-03)
API URL: https://w3id.org/oc/index/api/v1
Contact: contact@opencitations.net
License: This document is licensed with a Creative Commons Attribution 4.0 International License, while the REST API itself has been created using RAMOSE, the Restful API Manager Over SPARQL Endpoints created by Silvio Peroni, which is licensed with an ISC license.

Table of content

  1. Description
  2. Parameters
  3. Operations
    • /references/{doi}: This operation retrieves the citation data for all the references to other works appearing in the bibliographic entity identified by the input DOI.
    • /citations/{doi}: This operation retrieves the citation data for all the references appearing in other works to the bibliographic entity identified by the input DOI.
    • /citation/{oci}: This operation retrieves the citation data for the citation identified by the input Open Citation Identifier (OCI).
    • /metadata/{dois}: This operation retrieves the metadata for all the articles identified by the input DOIs.

1. Description back to toc

This document describe the REST API for accessing the data stored in all the OpenCitations Indexes hosted by OpenCitations. This API implements operations to retrieve the citation data for all the references to other works appearing in a particular bibliographic entity, or the citation data for all the references appearing in other works to a particular bibliographic entity, given the DOI of a bibliographic entity, or to retrieve citation data about a particular citation identified by means of its Open Citation Identifier (OCI).

All the present operations return either a JSON document (default) or a CSV document according to the mimetype specified in the Accept header of the request. If you would like to suggest an additional operation to be included in this API, please use the issue tracker of the OpenCitations APIs available on GitHub.

2. Parameters back to toc

Parameters can be used to filter and control the results returned by the API. They are passed as normal HTTP parameters in the URL of the call. They are:

  1. exclude=<field_name>: all the rows that have an empty value in the <field_name> specified are removed from the result set - e.g. exclude=given_name removes all the rows that do not have any string specified in the given_name field.

  2. filter=<field_name>:<operator><value>: only the rows compliant with <value> are kept in the result set. The parameter <operation> is not mandatory. If <operation> is not specified, <value> is interpreted as a regular expression, otherwise it is compared by means of the specified operation. Possible operators are "=", "<", and ">". For instance, filter=title:semantics? returns all the rows that contain the string "semantic" or "semantics" in the field title, while filter=date:>2016-05 returns all the rows that have a date greater than May 2016.

  3. sort=<order>(<field_name>): sort in ascending (<order> set to "asc") or descending (<order> set to "desc") order the rows in the result set according to the values in <field_name>. For instance, sort=desc(date) sorts all the rows according to the value specified in the field date in descending order.

  4. format=<format_type>: the final table is returned in the format specified in <format_type> that can be either "csv" or "json" - e.g. format=csv returns the final table in CSV format. This parameter has higher priority of the type specified through the "Accept" header of the request. Thus, if the header of a request to the API specifies Accept: text/csv and the URL of such request includes format=json, the final table is returned in JSON.

  5. json=<operation_type>("<separator>",<field>,<new_field_1>,<new_field_2>,...): in case a JSON format is requested in return, tranform each row of the final JSON table according to the rule specified. If <operation_type> is set to "array", the string value associated to the field name <field> is converted into an array by splitting the various textual parts by means of <separator>. For instance, considering the JSON table [ { "names": "Doe, John; Doe, Jane" }, ... ], the execution of array("; ",names) returns [ { "names": [ "Doe, John", "Doe, Jane" ], ... ]. Instead, if <operation_type> is set to "dict", the string value associated to the field name <field> is converted into a dictionary by splitting the various textual parts by means of <separator> and by associating the new fields <new_field_1>, <new_field_2>, etc., to these new parts. For instance, considering the JSON table [ { "name": "Doe, John" }, ... ], the execution of dict(", ",name,fname,gname) returns [ { "name": { "fname": "Doe", "gname": "John" }, ... ].

It is possible to specify one or more filtering operation of the same kind (e.g. exclude=given_name&exclude=family_name). In addition, these filtering operations are applied in the order presented above - first all the exclude operation, then all the filter operations followed by all the sort operation, and finally the format and the json operation (if applicable). It is worth mentioning that each of the aforementioned rules is applied in order, and it works on the structure returned after the execution of the previous rule.

Example: <api_operation_url>?exclude=doi&filter=date:>2015&sort=desc(date).

3. Operations back to toc

The operations that this API implements are:

/references/{doi} back to operations

This operation retrieves the citation data for all the references to other works appearing in the bibliographic entity identified by the input DOI.

The fields returned by this operation are:

The values of all the fields are prefixed with [index name] =>, so as to cleary identify from where the related data is coming, and can contain one or more information, separated by ;. This is particularly useful when a citation is actually contained in two or more OpenCitations Indexes. In this case, only one row will be returned, and the prefix used in the various data allows one to understand the source Index of such data.

Accepted HTTP method(s): get

Parameter(s):

Result fields: oci (str), citing (str), cited (str), creation (datetime), timespan (duration), ?journal_sc (str), ?author_sc (str)

Example: /references/10.1186/1756-8722-6-59

Exemplar output (in JSON)

[
    {
        "oci": "coci => 02001010806360107050663080702026306630509-0200101080636102703040309",
        "citing": "coci => 10.1186/1756-8722-6-59",
        "cited": "coci => 10.1186/ar3439",
        "creation": "coci => 2013",
        "timespan": "coci => P2Y",
        "journal_sc": "coci => no",
        "author_sc": "coci => no"
    },
    {
        "oci": "coci => 02001010806360107050663080702026306630509-0200101080636102704000806",
        "citing": "coci => 10.1186/1756-8722-6-59",
        "cited": "coci => 10.1186/ar4086",
        "creation": "coci => 2013",
        "timespan": "coci => P1Y",
        "journal_sc": "coci => no",
        "author_sc": "coci => no"
    },
    {
        "oci": "coci => 02001010806360107050663080702026306630509-020010200003619122437020001023704023707090006",
        "citing": "coci => 10.1186/1756-8722-6-59",
        "cited": "coci => 10.1200/jco.2012.42.7906",
        "creation": "coci => 2013",
        "timespan": "coci => P0Y",
        "journal_sc": "coci => no",
        "author_sc": "coci => no"
    },
    {
        "oci": "coci => 02001010806360107050663080702026306630509-02003010009360008080300010805370200010237060604070907",
        "citing": "coci => 10.1186/1756-8722-6-59",
        "cited": "coci => 10.3109/08830185.2012.664797",
        "creation": "coci => 2013",
        "timespan": "coci => P0Y",
        "journal_sc": "coci => no",
        "author_sc": "coci => no"
    }
]

/citations/{doi} back to operations

This operation retrieves the citation data for all the references appearing in other works to the bibliographic entity identified by the input DOI.

The fields returned by this operation are:

The values of all the fields are prefixed with [index name] =>, so as to cleary identify from where the related data is coming, and can contain one or more information, separated by ;. This is particularly useful when a citation is actually contained in two or more OpenCitations Indexes. In this case, only one row will be returned, and the prefix used in the various data allows one to understand the source Index of such data.

Accepted HTTP method(s): get

Parameter(s):

Result fields: oci (str), citing (str), cited (str), creation (datetime), timespan (duration), ?journal_sc (str), ?author_sc (str)

Example: /citations/10.1002/adfm.201505328

Exemplar output (in JSON)

[
    {
        "oci": "coci => 0200100030836231029271431221029283702000106370908-02001000002361013152237020001050005030208",
        "citing": "coci => 10.1038/natrevmats.2016.98",
        "cited": "coci => 10.1002/adfm.201505328",
        "creation": coci/"2017-01-17",
        "timespan": "coci => P11M"
        "journal_sc": "coci => no",
        "author_sc": "coci => no"
    },
    {
        "oci": "coci => 02001000002361013221037020001070002060708-02001000002361013152237020001050005030208",
        "citing": "coci => 10.1002/adma.201702678",
        "cited": "coci => 10.1002/adfm.201505328",
        "creation": "coci => 2017-07-25",
        "timespan": "coci => P1Y5M8D"
        "journal_sc": "coci => no",
        "author_sc": "coci => no"
    },
    {
        "oci": "coci => 020010003083623142314271634370200010737010005-02001000002361013152237020001050005030208",
        "citing": "coci => 10.1038/nenergy.2017.105",
        "cited": "coci => 10.1002/adfm.201505328",
        "creation": "coci => 2017-07-10",
        "timespan": "coci => P1Y4M23D"
        "journal_sc": "coci => no",
        "author_sc": "coci => no"
    }
]

/citation/{oci} back to operations

This operation retrieves the citation data for the citation identified by the input Open Citation Identifier (OCI).

The Open Citation Identifier is a globally unique persistent identifier for bibliographic citations, which has a simple structure: the lower-case letters "oci" followed by a colon, followed by two numbers separated by a dash. For example, oci:1-18 is a valid OCI.

It is worth mentioning that, in this REST operation, the prefix "oci:" should not be specified, and only the dash-separated numbers of the OCI should be provided, as shown in the example below.

The fields returned by this operation are:

The values of all the fields are prefixed with [index name] =>, so as to cleary identify from where the related data is coming, and can contain one or more information, separated by ;. This is particularly useful when a citation is actually contained in two or more OpenCitations Indexes. In this case, only one row will be returned, and the prefix used in the various data allows one to understand the source Index of such data.

Accepted HTTP method(s): get

Parameter(s):

Result fields: oci (str), citing (str), cited (str), creation (datetime), timespan (duration), ?journal_sc (str), ?author_sc (str)

Example: /citation/02001010806360107050663080702026306630509-0200101080636102704000806

Exemplar output (in JSON)

[
    {
        "oci": "coci => 02001010806360107050663080702026306630509-0200101080636102704000806",
        "citing": "coci => 10.1186/1756-8722-6-59",
        "cited": "coci => 10.1186/ar4086",
        "creation": "coci => 2013",
        "timespan": "coci => P1Y",
        "journal_sc": "coci => no",
        "author_sc": "coci => no"
    }
]

/metadata/{dois} back to operations

This operation retrieves the metadata for all the articles identified by the input DOIs.

It is possible to specify one or more DOIs as input of this operation. In this case, the DOI should be separated with a double underscore ("__") – e.g. "10.1108/jd-12-2013-0166__10.1016/j.websem.2012.08.001__...". The fields returned by this operation are:

Note: this operation strictly depends on external services (i.e. doi.org and associate applications) for gathering all the metadata of the articles requested. In fact, these metadata are not stored in COCI and are retrieved dynamically upon request.

Accepted HTTP method(s): get

Parameter(s):

Result fields: author (str), year (datetime), title (str), source_title (str), source_id (str), volume (str), issue (str), page (str), doi (str), reference (str), citation (str), citation_count (int), oa_link (str)

Example: /metadata/10.1108/jd-12-2013-0166__10.6084/m9.figshare.3443876

Exemplar output (in JSON)

[
    {
        "citation": "10.1177/0961000615616450; 10.7554/elife.32822; 10.1145/3197026.3197050; 10.1093/bib/bbx057; 10.1007/978-3-319-68204-4_19; 10.3346/jkms.2015.30.11.1545; 10.1007/978-3-319-73165-0_24; 10.3233/sw-160224; 10.3233/sw-180307; 10.1007/978-3-319-90548-8_7; 10.1142/s021964921850034x; 10.1007/978-3-319-58694-6_23; 10.1057/s41275-017-0070-x",
        "reference": "10.1001/jama.295.1.90; 10.1002/asi.4630240406; 10.1002/(sici)1097-4571(198909)40:5<342::aid-asi7>3.0.co;2-u; 10.1007/bf02457980; 10.1007/s10579-012-9211-2; 10.1007/s11192-009-0021-2; 10.1016/j.websem.2012.08.001; 10.1016/j.websem.2013.05.001; 10.1023/a:1021919228368; 10.1038/35079151; 10.1038/495437a; 10.1038/502295a; 10.1038/502298a; 10.1042/bj20091474; 10.1073/pnas.0407743101; 10.1087/2009202; 10.1093/bioinformatics; 10.1101/sqb.1972.036.01.015; 10.1108/eum0000000007123; 10.1108/jd-07-2012-0082; 10.1126/science.149.3683.510; 10.1136/bmj.a568; 10.1136/bmj.b2680; 10.1145/1498765.1498780; 10.1177/030631277400400102; 10.1177/030631277500500106; 10.1371/journal.pcbi.0010034; 10.1371/journal.pcbi.1000361; 10.1371/journal.pntd.0000228; 10.1371/journal.pone.0000308; 10.1523/jneurosci.0003-08.2008; 10.1525/bio.2010.60.5.2; 10.3115/1610075.1610091; 10.5210/fm.v2i4.522; 10.5539/ass.v9n5p18; 10.7717/peerj.175",
        "author": "Peroni, Silvio; Dutton, Alexander; Gray, Tanya; Shotton, David",
        "volume": "71",
        "page": "253-277",
        "citation_count": "13",
        "source_id": "issn:0022-0418",
        "source_title": "Journal Of Documentation",
        "year": "2015",
        "oa_link": "",
        "doi": "10.1108/jd-12-2013-0166",
        "title": "Setting Our Bibliographic References Free: Towards Open Citation Data",
        "issue": "2"
    },
    {
        "citation": "10.1007/978-3-319-68204-4_19",
        "reference": "",
        "author": "Peroni, Silvio, 0000-0003-0530-4305; Shotton, David, 0000-0001-5506-523X",
        "volume": "",
        "page": "",
        "citation_count": "1",
        "source_id": "",
        "source_title": "Figshare",
        "year": "2018",
        "oa_link": "",
        "doi": "10.6084/m9.figshare.3443876",
        "title": "The OpenCitations Data Model",
        "issue": ""
    }
]