REST API of the Open Biomedical Citations in Context Corpus (CCC)

Version: 1.0.0
API URL: https://w3id.org/oc/ccc/api/v1
Contact: marilena.daquino@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, which is licensed with an ISC license.

Description back to top

This document describes the REST API of the Open Biomedical Citations in Context Corpus (CCC) hosted by OpenCitations. All the operations described in this document return either a JSON document (default) or a CSV document according to the mimetype specified in the Accept header of the request.

The CCC is based on the Open Access subset of XML articles served by Europe PubMed Central API. It includes information mined from the full-text of articles, such as in-text references (e.g. (Daquino et al. 2020)), structural elements (sentences, paragraphs, footnotes, captions, tables, and sections), rhetorical elements (e.g. section "Methods"), and the sequential number of the structural elements including in-text reference pointers (e.g. sentence 5, paragraph 2, section 1 "Introduction").

We extend the definition of Open Citation Identifier (OCI) in order to identify citation links that are related to a specific in-text reference pointer, that is, the textual device that references a cited resource in the full-text of the citing resource. Specifically, OCI may appear in the form <citing_id>-<cited_id>{/<nth-occurrence>}, where:

• <citing_id> is the local identifier assigned to the citing resource in CCC
• <cited_id> is the local identifier assigned to the cited resource in CCC
• <nth-occurrence>, is the nth in-text reference pointer at hand denoting the cited resource (if applicable).

For instance 0701-0709/1 identifies the 1st in-text reference appearing in (the text of) the citing article 0701 that is related to the cited article 0709.

Moreover, CCC introduces the usage of In-Text Reference Pointer IDentifier (InTRePID) to identify in-text reference pointers. It is based on OCI, and it appears in the form <citing_id>-<cited_id>/<nth-occurrence>-<total-count>, where:

• <citing_id> is the local identifier assigned to the citing resource in CCC
• <cited_id> is the local identifier assigned to the cited resource in CCC
• <nth-occurrence>, is the nth in-text reference pointer at hand denoting the cited resource (if applicable).
• <total-count> corresponds to the total number of in-text reference pointers related to the same citation.

For instance, 0701-0709/1-2 and 0701-0709/2-2 represent the first and the second in-text reference pointer respectively that appear in the citing article 0701 that are related to the cited article 0709. InTrePIDs are dereferencable and the InTrePID resolution service allows one to retrieve the citation context of a given InTrePID (such as identifiers of sentences, paragraphs, and sections where an in-text reference pointer appears).

If you would like to suggest additional operations, please use the CCC issue tracker available on GitHub to contact us.

If you are going to use the REST APIs within an application/code, we encourage you to get the OpenCitations Access Token and specify it in the "authorization" header of your REST API call. Here is a usage example in Python:

from requests import get

API_CALL = "https://opencitations.net/ccc/api/v1/metadata/10.1126/science.aat5031__10.1084/jem.20200891"
HTTP_HEADERS = {"authorization": "YOUR-OPENCITATIONS-ACCESS-TOKEN"}

get(API_CALL, headers=HTTP_HEADERS)

Parameters back to top

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. require=<field_name>: all the rows that have an empty value in the <field_name> specified are removed from the result set - e.g. require=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. require=given_name&require=family_name). In addition, these filtering operations are applied in the order presented above - first all the require 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>?require=doi&filter=date:>2015&sort=desc(date).