-
Notifications
You must be signed in to change notification settings - Fork 1
/
croci_v1.hf
288 lines (255 loc) · 15.5 KB
/
croci_v1.hf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
#url /api/v1
#type api
#base https://opencitations.net/index/croci
#title REST API for CROCI, the Croudsourced Open Citations Index
#description This document describe the REST API for accessing the data stored in [CROCI](https://w3id.org/oc/index/croci) 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 DOI 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/croci/api/v1/references/10.1002/asi.20755"
HTTP_HEADERS = {"authorization": "YOUR-OPENCITATIONS-ACCESS-TOKEN"}
get(API_CALL, headers=HTTP_HEADERS)
</code></pre>
<p style="color: #CC0000"><strong>Note:</strong> we use certain legacy APIs for historical and compatibility reasons. While we encourage the use of our latest and more efficient <a href="https://opencitations.net/index/api/v2">V2 APIs</a>, we understand that some applications may still rely on these older endpoints. Please note that legacy APIs may not receive updates or support, and their use may be phased out in the future. We recommend transitioning to our current <a href="https://opencitations.net/index/api/v2">V2 APIs</a> for improved performance, security, and reliability.</p>
#version Version 1.2.0 (2023-11-06)
#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 /citation/{oci}
#type operation
#oci str([0-9]+-[0-9]+)
#postprocess citations_info(oci,citing,cited,"doi")
#method get
#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 DOI of the citing entity;
* *cited*: the DOI 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).
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.
#call /citation/062401300477-06180353247
#output_json [
{
"oci": "062401300477-06180353247",
"citing": "10.1002/asi.20755",
"cited": "10.1038/438900a",
"creation": "2007",
"timespan": "P1Y",
"journal_sc": "no",
"author_sc": "no"
}
]
#field_type str(oci) str(citing) str(cited)
#sparql PREFIX cito: <http://purl.org/spar/cito/>
SELECT ?oci ?citing ?cited
WHERE {
VALUES ?oci {<https://w3id.org/oc/index/ci/[[oci]]>} .
?oci ?p <https://w3id.org/oc/index/croci/> .
?oci cito:hasCitingEntity ?citing .
?oci cito:hasCitedEntity ?cited .
}
LIMIT 50000
#url /citation-count/{doi}
#type operation
#doi str(10\..+)
#preprocess lower(doi) --> doi2omid(doi)
#method get
#description This operation retrieves the number of incoming citations to the bibliographic entity identified by the input DOI.
The field returned by this operation is:
* *count*: the number of incoming citations to the input bibliographic entity.
#call /citation-count/10.1038/438900a
#field_type int(count)
#output_json [
{
"count": "1"
}
]
#sparql PREFIX cito: <http://purl.org/spar/cito/>
SELECT (count(?citing) as ?count)
WHERE {
?oci cito:hasCitedEntity <https://w3id.org/oc/meta/br/[[doi]]> .
?oci ?p <https://w3id.org/oc/index/croci/> .
?oci cito:hasCitingEntity ?citing .
}
#url /reference-count/{doi}
#type operation
#doi str(10\..+)
#preprocess lower(doi) --> doi2omid(doi)
#method get
#description This operation retrieves the number of outgoing citations from the bibliographic entity identified by the input DOI.
The field returned by this operation is:
* *count*: the number of outgoing citations from the input bibliographic entity.
#call /reference-count/10.1002/asi.20755
#field_type int(count)
#output_json [
{
"count": "13"
}
]
#sparql PREFIX cito: <http://purl.org/spar/cito/>
SELECT (count(?cited) as ?count)
WHERE {
?oci cito:hasCitingEntity <https://w3id.org/oc/meta/br/[[doi]]> .
?oci ?p <https://w3id.org/oc/index/croci/> .
?oci cito:hasCitedEntity ?cited .
}
#url /metadata/{dois}
#type operation
#dois str(\"?10\..+[^_\"]((__|\" \")10\..+[^_])*\"?)
#preprocess lower(dois) --> split_dois2omids(dois)
#postprocess metadata(val,citation,reference)
#method get
#description This operation retrieves the bibliographic metadata for each of the bibliographic entities identified by one or more 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:
* *author*: the semicolon-separated list of authors of the bibliographic entity;
* *year*: the year of publication of the bibliographic entity;
* *title*: the title of the bibliographic entity;
* *source_title*: the title of the venue where the bibliographic entity has been published;
* *source_id*: the semicolon-separated list of identifiers referring to the source where the bibliographic entity has been published;
* *volume*: the number of the volume in which the bibliographic entity has been published;
* *issue*: the number of the issue in which the bibliographic entity has been published;
* *page*: the starting and ending pages of the bibliographic entity in the context of the venue where it has been published;
* *doi*: the DOI of the bibliographic entity;
* *reference*: the semicolon-separated DOIs of all the entities cited by the bibliographic entity, according to the citation data available in all the OpenCitations Indexes;
* *citation*: the semicolon-separated DOIs of all the entities that cite the bibliographic entity, according to the citation data available in all the OpenCitations Indexes;
* *citation_count*: the number of citations received by the bibliographic entity;
* *oa_link*: the link to the Open Access version of the bibliographic entity, if available.
Note: this operation gathers all the metadata dynamically upon request from OpenCitations Meta.
#call /metadata/10.1038/438900a
#field_type str(author) datetime(year) str(title) str(source_title) str(source_id) str(volume) str(issue) str(page) str(doi) str(reference) str(citation) int(citation_count) str(oa_link)
#output_json [
{
"doi": "10.1038/438900a",
"citation_count": "1",
"citation": "10.1002/asi.20755",
"reference": "",
"author": "Giles, Jim",
"year": "2005-12",
"title": "Internet Encyclopaedias Go Head To Head",
"source_title": "Nature",
"volume": "438",
"issue": "7070",
"page": "900-901",
"source_id": "issn:1476-4687",
"oa_link": ""
}
]
#sparql PREFIX cito: <http://purl.org/spar/cito/>
SELECT ?val (GROUP_CONCAT(?citing; separator="; ") as ?citation) (GROUP_CONCAT(?cited; separator="; ") as ?reference) {
{
VALUES ?val { [[dois]] }
?oci cito:hasCitingEntity ?val .
?oci ?p <https://w3id.org/oc/index/croci/> .
?oci cito:hasCitedEntity ?cited .
}
UNION
{
VALUES ?val { [[dois]] }
?oci cito:hasCitedEntity ?val .
?oci ?p <https://w3id.org/oc/index/croci/> .
?oci cito:hasCitingEntity ?citing .
}
} GROUP BY ?val
#url /citations/{doi}
#type operation
#doi str(10\..+)
#preprocess lower(doi) --> doi2omid(doi)
#postprocess citations_info(oci,citing,cited,"doi")
#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 DOI, 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 DOI of the citing entity;
* *cited*: the DOI 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).
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.
#call /citations/10.1038/438900a
#output_json [
{
"oci": "062401300477-06180353247",
"citing": "10.1002/asi.20755",
"cited": "10.1038/438900a",
"creation": "2007",
"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
WHERE {
?oci cito:hasCitedEntity <https://w3id.org/oc/meta/br/[[doi]]> .
?oci ?p <https://w3id.org/oc/index/croci/> .
?oci cito:hasCitingEntity ?citing .
BIND(<https://w3id.org/oc/meta/br/[[doi]]> as ?cited) .
}
LIMIT 50000
#url /references/{doi}
#type operation
#doi str(10\..+)
#preprocess lower(doi) --> doi2omid(doi)
#postprocess citations_info(oci,citing,cited,"doi")
#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 DOI.
The fields returned by this operation are:
* *oci*: the Open Citation Identifier (OCI) of the citation in consideration;
* *citing*: the DOI of the citing entity;
* *cited*: the DOI 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).
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.
#call /references/10.1002/asi.20755
#output_json [
{
"oci": "062401300477-06101842879",
"citing": "10.1002/asi.20755",
"cited": "10.2307/1562247",
"creation": "2007",
"timespan": "P4Y",
"journal_sc": "no",
"author_sc": "no"
},
{
"oci": "062401300477-06150873134",
"citing": "10.1002/asi.20755",
"cited": "10.2307/4486062",
"creation": "2007",
"timespan": "P0Y",
"journal_sc": "no",
"author_sc": "no"
},
{
"oci": "062401300477-06170317033",
"citing": "10.1002/asi.20755",
"cited": "10.2307/2529310",
"creation": "2007",
"timespan": "P29Y",
"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
WHERE {
?oci cito:hasCitingEntity <https://w3id.org/oc/meta/br/[[doi]]> .
?oci ?p <https://w3id.org/oc/index/croci/> .
?oci cito:hasCitedEntity ?cited .
BIND(<https://w3id.org/oc/meta/br/[[doi]]> as ?citing) .
}
LIMIT 50000