noci_v1.hf

#url /api/v1
#type api
#base https://w3id.org/oc/index/noci
#title REST API for NOCI, the OpenCitations Index of the National Institute of Health Open Citation Collection open PMID-to-PMID references
#description This document describe the REST API for accessing the data stored in [NOCI](https://w3id.org/oc/index/noci) hosted by [OpenCitations](http://opencitations.net). 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 PMID of a bibliographic entity, or to retrieve citation data about a particular citation identified by means of its [Open Citation Identifier (OCI)](https://opencitations.wordpress.com/2018/03/12/citations-as-first-class-data-entities-open-citation-identifiers/).

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](https://github.com/opencitations/api/issues) of the OpenCitations APIs available on GitHub.

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

<pre style="height: 150px"><code>
from requests import get

API_CALL = "https://opencitations.net/index/noci/api/v1/references/10.1186/1756-8722-6-59"
HTTP_HEADERS = {"authorization": "YOUR-OPENCITATIONS-ACCESS-TOKEN"}

get(API_CALL, headers=HTTP_HEADERS)
</code></pre>

#version Version 1.3.0 (2020-03-25)
#contacts [contact@opencitations.net](mailto:contact@opencitations.net)
#license This document is licensed with a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/legalcode), while the REST API itself has been created using [RAMOSE](https://github.com/opencitations/ramose), the *Restful API Manager Over SPARQL Endpoints* created by [Silvio Peroni](https://orcid.org/0000-0003-0530-4305), which is licensed with an [ISC license](https://opensource.org/licenses/ISC).
#endpoint http://127.0.0.1/index/sparql
#method post
#addon indexapi_v1

#url /references/{pmid}
#type operation
#pmid str(\d+)
#method get
#description This operation retrieves the citation data for all the outgoing references to other cited works appearing in the reference list of the bibliographic entity identified by the input PMID.

The fields returned by this operation are:

* *oci*: the Open Citation Identifier (OCI) of the citation in consideration;
* *citing*: the PMID of the citing entity;
* *cited*: the PMID of the cited entity;
* *creation*: the creation date of the citation according to the [ISO date format](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DD`, which corresponds to the publication date of the citing entity;
* *timespan*: the interval between the publication date of the cited entity and the publication date of the citing entity, expressed using the [XSD duration format](https://www.w3.org/TR/xmlschema11-2/#duration) `PnYnMnD`;
* *journal_sc*: it records whether the citation is a journal self-citations (i.e. the citing and the cited entities are published in the same journal);
* *author_sc*: it records whether the citation is an author self-citation (i.e. the citing and the cited entities have at least one author in common).
#call /references/10.1186/1756-8722-6-59
#output_json [
    {
        "oci": "02001010806360107050663080702026306630509-0200101080636102703040309",
        "citing": "10.1186/1756-8722-6-59",
        "cited": "10.1186/ar3439",
        "creation": "2013",
        "timespan": "P2Y",
        "journal_sc": "no",
        "author_sc": "no"
    },
    {
        "oci": "02001010806360107050663080702026306630509-0200101080636102704000806",
        "citing": "10.1186/1756-8722-6-59",
        "cited": "10.1186/ar4086",
        "creation": "2013",
        "timespan": "P1Y",
        "journal_sc": "no",
        "author_sc": "no"
    },
    {
        "oci": "02001010806360107050663080702026306630509-020010200003619122437020001023704023707090006",
        "citing": "10.1186/1756-8722-6-59",
        "cited": "10.1200/jco.2012.42.7906",
        "creation": "2013",
        "timespan": "P0Y",
        "journal_sc": "no",
        "author_sc": "no"
    },
    {
        "oci": "02001010806360107050663080702026306630509-02003010009360008080300010805370200010237060604070907",
        "citing": "10.1186/1756-8722-6-59",
        "cited": "10.3109/08830185.2012.664797",
        "creation": "2013",
        "timespan": "P0Y",
        "journal_sc": "no",
        "author_sc": "no"
    }
]
#field_type str(oci) str(citing) str(cited) datetime(creation) duration(timespan) str(?journal_sc) str(?author_sc)
#sparql PREFIX cito: <http://purl.org/spar/cito/>
SELECT ?oci ?citing ?cited ?creation ?timespan (IF(bound(?jsc), "yes", "no") as ?journal_sc) (IF(bound(?asc), "yes", "no") as ?author_sc)
WHERE {
    GRAPH <https://w3id.org/oc/index/noci/> {
        BIND(<https://pubmed.ncbi.nlm.nih.gov/[[pmid]]> as ?citing_iri) .
        ?citing_iri ^cito:hasCitingEntity ?oci_iri .
        ?oci_iri
            cito:hasCitedEntity ?cited_iri ;
            cito:hasCitationCreationDate ?creation ;
            cito:hasCitationTimeSpan ?timespan .

        OPTIONAL {
            ?oci_iri a cito:JournalSelfCitation .
            BIND("yes" as ?jsc)
        }

        OPTIONAL {
            ?oci_iri a cito:AuthorSelfCitation .
            BIND("yes" as ?asc)
        }

        BIND(STRAFTER(str(?citing_iri), "https://pubmed.ncbi.nlm.nih.gov/") AS ?citing)
        BIND(STRAFTER(str(?cited_iri), "https://pubmed.ncbi.nlm.nih.gov/") AS ?cited)
        BIND(STRAFTER(str(?oci_iri), "/ci/") AS ?oci)
    }
}
LIMIT 50000

#url /citations/{pmid}
#type operation
#pmid str(\d+)
#preprocess lower(pmid) --> encode(pmid)
#postprocess decode_doi(citing, cited)
#method get
#description This operation retrieves the citation data for all the references appearing in the reference lists of other citing works to the bibliographic entity identified by the input PMID, that constitute the incoming citations of that identified bibliographic entity.

The fields returned by this operation are:

* *oci*: the Open Citation Identifier (OCI) of the citation in consideration;
* *citing*: the PMID of the citing entity;
* *cited*: the PMID of the cited entity;
* *creation*: the creation date of the citation according to the [ISO date format](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DD`, which corresponds to the publication date of the citing entity;
* *timespan*: the interval between the publication date of the cited entity and the publication date of the citing entity, expressed using the [XSD duration format](https://www.w3.org/TR/xmlschema11-2/#duration) `PnYnMnD`;
* *journal_sc*: it records whether the citation is a journal self-citations (i.e. the citing and the cited entities are published in the same journal);
* *author_sc*: it records whether the citation is an author self-citation (i.e. the citing and the cited entities have at least one author in common).
#call /citations/10.1002/adfm.201505328
#output_json [
    {
        "oci": "0200100030836231029271431221029283702000106370908-02001000002361013152237020001050005030208",
        "citing": "10.1038/natrevmats.2016.98",
        "cited": "10.1002/adfm.201505328",
        "creation": "2017-01-17",
        "timespan": "P11M"
        "journal_sc": "no",
        "author_sc": "no"
    },
    {
        "oci": "02001000002361013221037020001070002060708-02001000002361013152237020001050005030208",
        "citing": "10.1002/adma.201702678",
        "cited": "10.1002/adfm.201505328",
        "creation": "2017-07-25",
        "timespan": "P1Y5M8D"
        "journal_sc": "no",
        "author_sc": "no"
    },
    {
        "oci": "020010003083623142314271634370200010737010005-02001000002361013152237020001050005030208",
        "citing": "10.1038/nenergy.2017.105",
        "cited": "10.1002/adfm.201505328",
        "creation": "2017-07-10",
        "timespan": "P1Y4M23D"
        "journal_sc": "no",
        "author_sc": "no"
    }
]
#field_type str(oci) str(citing) str(cited) datetime(creation) duration(timespan) str(?journal_sc) str(?author_sc)
#sparql PREFIX cito: <http://purl.org/spar/cito/>
SELECT ?oci ?citing ?cited ?creation ?timespan (IF(bound(?jsc), "yes", "no") as ?journal_sc) (IF(bound(?asc), "yes", "no") as ?author_sc)
WHERE {
    GRAPH <https://w3id.org/oc/index/noci/> {
        BIND(<https://pubmed.ncbi.nlm.nih.gov/[[pmid]]> as ?cited_iri) .
        ?cited_iri ^cito:hasCitedEntity ?oci_iri .
        ?oci_iri
            cito:hasCitingEntity ?citing_iri ;
            cito:hasCitationCreationDate ?creation ;
            cito:hasCitationTimeSpan ?timespan .

        OPTIONAL {
            ?oci_iri a cito:JournalSelfCitation .
            BIND("yes" as ?jsc)
        }

        OPTIONAL {
            ?oci_iri a cito:AuthorSelfCitation .
            BIND("yes" as ?asc)
        }

        BIND(STRAFTER(str(?citing_iri), "https://pubmed.ncbi.nlm.nih.gov/") AS ?citing)
        BIND(STRAFTER(str(?cited_iri), "https://pubmed.ncbi.nlm.nih.gov/") AS ?cited)
        BIND(STRAFTER(str(?oci_iri), "/ci/") AS ?oci)
    }
}
LIMIT 50000

#url /citation/{oci}
#type operation
#oci str([0-9]+-[0-9]+)
#method get
#postprocess decode_doi(citing, cited)
#description This operation 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, 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:

* *oci*: the Open Citation Identifier (OCI) of the citation in consideration;
* *citing*: the PMID of the citing entity;
* *cited*: the PMID of the cited entity;
* *creation*: the creation date of the citation according to the [ISO date format](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DD`, which corresponds to the publication date of the citing entity;
* *timespan*: the interval between the publication date of the cited entity and the publication date of the citing entity, expressed using the [XSD duration format](https://www.w3.org/TR/xmlschema11-2/#duration) `PnYnMnD`;
* *journal_sc*: it records whether the citation is a journal self-citations (i.e. the citing and the cited entities are published in the same journal);
* *author_sc*: it records whether the citation is an author self-citation (i.e. the citing and the cited entities have at least one author in common).
#call /citation/02001010806360107050663080702026306630509-0200101080636102704000806
#output_json [
    {
        "oci": "02001010806360107050663080702026306630509-0200101080636102704000806",
        "citing": "10.1186/1756-8722-6-59",
        "cited": "10.1186/ar4086",
        "creation": "2013",
        "timespan": "P1Y",
        "journal_sc": "no",
        "author_sc": "no"
    }
]
#field_type str(oci) str(citing) str(cited) datetime(creation) duration(timespan) str(?journal_sc) str(?author_sc)
#sparql PREFIX cito: <http://purl.org/spar/cito/>
SELECT ?oci ?citing ?cited ?creation ?timespan (IF(bound(?jsc), "yes", "no") as ?journal_sc) (IF(bound(?asc), "yes", "no") as ?author_sc)
WHERE {
    GRAPH <https://w3id.org/oc/index/noci/> {
        BIND(<https://w3id.org/oc/index/noci/ci/[[oci]]> as ?oci_iri) .
        ?oci_iri
            cito:hasCitingEntity ?citing_iri ;
            cito:hasCitedEntity ?cited_iri ;
            cito:hasCitationCreationDate ?creation ;
            cito:hasCitationTimeSpan ?timespan .

        OPTIONAL {
            ?oci_iri a cito:JournalSelfCitation .
            BIND("yes" as ?jsc)
        }

        OPTIONAL {
            ?oci_iri a cito:AuthorSelfCitation .
            BIND("yes" as ?asc)
        }

        BIND(STRAFTER(str(?citing_iri), "https://pubmed.ncbi.nlm.nih.gov/") AS ?citing)
        BIND(STRAFTER(str(?cited_iri), "https://pubmed.ncbi.nlm.nih.gov/") AS ?cited)
        BIND(STRAFTER(str(?oci_iri), "/ci/") AS ?oci)
    }
}
LIMIT 50000

#url /citation-count/{pmid}
#type operation
#pmid str(\d+)
#preprocess lower(pmid) --> encode(pmid)
#method get
#description This operation retrieves the number of incoming citations to the bibliographic entity identified by the input PMID.

The field returned by this operation is:

* *count*: the number of incoming citations to the input bibliographic entity.
#call /citation-count/10.1002/adfm.201505328
#field_type int(count)
#output_json [
    {
        "count": "124"
    }
]
#sparql PREFIX cito: <http://purl.org/spar/cito/>
SELECT (count(?c) as ?count)
WHERE {
    GRAPH <https://w3id.org/oc/index/noci/> {
        BIND(<https://pubmed.ncbi.nlm.nih.gov/[[pmid]]> as ?cited) .
		?cited ^cito:hasCitedEntity ?c
    }
}

#url /reference-count/{pmid}
#type operation
#pmid str(\d+)
#preprocess lower(pmid) --> encode(pmid)
#method get
#description This operation retrieves the number of outgoing citations from the bibliographic entity identified by the input PMID.

The field returned by this operation is:

* *count*: the number of outgoing citations from the input bibliographic entity.
#call /reference-count/10.1002/adfm.201505328
#field_type int(count)
#output_json [
    {
        "count": "55"
    }
]
#sparql PREFIX cito: <http://purl.org/spar/cito/>
SELECT (count(?c) as ?count)
WHERE {
    GRAPH <https://w3id.org/oc/index/noci/> {
        BIND(<https://pubmed.ncbi.nlm.nih.gov/[[pmid]]> as ?citing) .
		?citing ^cito:hasCitingEntity ?c
    }
}