Revision 38756
Added by Alessia Bardi about 9 years ago
api-doc.html | ||
---|---|---|
1 | 1 |
<html><head> |
2 | 2 |
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
3 |
<title>OpenAIRE API documentation</title><link rel="stylesheet" type="text/css" href="openaire-api.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book"><div class="titlepage"><div><div><h1 class="title"><a name="d0e1"></a>OpenAIRE API documentation</h1></div><div><p class="pubdate">20 March 2015</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="#d0e9">1. Overview</a></span></dt><dt><span class="chapter"><a href="#cha_oai_pmh">2. Bulk access via OAI-PMH</a></span></dt><dt><span class="chapter"><a href="#cha_projects_http">3. Bulk access to projects</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e152">DSpace/ePrints</a></span></dt><dt><span class="section"><a href="#d0e194">Projects in TSV file</a></span></dt></dl></dd><dt><span class="chapter"><a href="#cha_http-api">4. Selective access with HTTP API</a></span></dt><dd><dl><dt><span class="section"><a href="#sec_http-common">Common API parameters</a></span></dt><dt><span class="section"><a href="#sec_http-pubs">Publications</a></span></dt><dt><span class="section"><a href="#sec_http-datasets">Datasets</a></span></dt><dt><span class="section"><a href="#sec_http-projects">Projects</a></span></dt></dl></dd></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="d0e9"></a>Chapter 1. Overview</h1></div></div></div><p>The OpenAIRE API allows developers to access the metadata information space of OpenAIRE |
|
4 |
programmatically.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bulk access:</p><table border="0" summary="Simple list" class="simplelist"><tr><td><a class="xref" href="#cha_oai_pmh" title="Chapter 2. Bulk access via OAI-PMH">OAI-PMH</a></td></tr><tr><td><a class="xref" href="#cha_projects_http" title="Chapter 3. Bulk access to projects">Bulk access to projects</a></td></tr></table></li><li class="listitem"><p>Selective access via <a class="xref" href="#cha_http-api" title="Chapter 4. Selective access with HTTP API">HTTP Search API</a></p><table border="0" summary="Simple list" class="simplelist"><tr><td><a class="xref" href="#sec_http-pubs" title="Publications">Search HTTP API for metadata about publications</a></td></tr><tr><td><a class="xref" href="#sec_http-datasets" title="Datasets">Search HTTP API for metadata about datasets</a></td></tr><tr><td><a class="xref" href="#sec_http-projects" title="Projects">Search HTTP API for metadata about projects</a></td></tr></table></li></ul></div><p> Please note that currently the total numbers of metadata returned by the <a class="xref" href="#cha_http-api" title="Chapter 4. Selective access with HTTP API">HTTP Search API</a> and the <a class="xref" href="#cha_oai_pmh" title="Chapter 2. Bulk access via OAI-PMH">OAI-PMH</a> are different because the first |
|
3 |
<title>OpenAIRE API documentation</title><link rel="stylesheet" type="text/css" href="openaire-api.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book"><div class="titlepage"><div><div><h1 class="title"><a name="d0e1"></a>OpenAIRE API documentation</h1></div><div><p class="pubdate">26 August 2015</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="#d0e9">1. Notes and messages from the OpenAIRE technical team</a></span></dt><dt><span class="chapter"><a href="#d0e30">2. Overview</a></span></dt><dt><span class="chapter"><a href="#cha_oai_pmh">3. Bulk access via OAI-PMH</a></span></dt><dt><span class="chapter"><a href="#cha_projects_http">4. Bulk access to projects</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e181">DSpace/ePrints</a></span></dt><dt><span class="section"><a href="#d0e223">Projects in TSV file</a></span></dt></dl></dd><dt><span class="chapter"><a href="#cha_http-api">5. Selective access with HTTP API</a></span></dt><dd><dl><dt><span class="section"><a href="#sec_http-common">Common API parameters</a></span></dt><dt><span class="section"><a href="#sec_http-pubs">Publications</a></span></dt><dt><span class="section"><a href="#sec_http-datasets">Datasets</a></span></dt><dt><span class="section"><a href="#sec_http-projects">Projects</a></span></dt></dl></dd></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="d0e9"></a>Chapter 1. Notes and messages from the OpenAIRE technical team</h1></div></div></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> |
|
4 |
During the summer period, OpenAIRE will perform some system upgrade and the API may be not available or respond slowly, in particular in the periods: |
|
5 |
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>from 5th August to 9th August</p></li><li class="listitem"><p>from 24th August to 28th August</p></li><li class="listitem"><p>from 31st August to 4th September</p></li></ul></div><p> |
|
6 |
</p><p>We apologise for any inconvenience this may cause,</p><p>the OpenAIRE technical team.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="d0e30"></a>Chapter 2. Overview</h1></div></div></div><p>The OpenAIRE API allows developers to access the metadata information space of OpenAIRE |
|
7 |
programmatically.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bulk access:</p><table border="0" summary="Simple list" class="simplelist"><tr><td><a class="xref" href="#cha_oai_pmh" title="Chapter 3. Bulk access via OAI-PMH">OAI-PMH</a></td></tr><tr><td><a class="xref" href="#cha_projects_http" title="Chapter 4. Bulk access to projects">Bulk access to projects</a></td></tr></table></li><li class="listitem"><p>Selective access via <a class="xref" href="#cha_http-api" title="Chapter 5. Selective access with HTTP API">HTTP Search API</a></p><table border="0" summary="Simple list" class="simplelist"><tr><td><a class="xref" href="#sec_http-pubs" title="Publications">Search HTTP API for metadata about publications</a></td></tr><tr><td><a class="xref" href="#sec_http-datasets" title="Datasets">Search HTTP API for metadata about datasets</a></td></tr><tr><td><a class="xref" href="#sec_http-projects" title="Projects">Search HTTP API for metadata about projects</a></td></tr></table></li></ul></div><p> Please note that currently the total numbers of metadata returned by the <a class="xref" href="#cha_http-api" title="Chapter 5. Selective access with HTTP API">HTTP Search API</a> and the <a class="xref" href="#cha_oai_pmh" title="Chapter 3. Bulk access via OAI-PMH">OAI-PMH</a> are different because the first |
|
5 | 8 |
discards duplicates. </p><p> The behaviour of the OAI-PMH publisher will be updated soon to not export |
6 | 9 |
duplicates.</p><p>The default format of delivered records is <code class="code">oaf</code> (OpenAire Format - current |
7 |
version 0.2): </p><table border="0" summary="Simple list" class="simplelist"><tr><td><a class="link" href="https://www.openaire.eu/schema/0.2/oaf-0.2.xsd" target="_top">https://www.openaire.eu/schema/0.2/oaf-0.2.xsd</a></td></tr><tr><td><a class="link" href="https://www.openaire.eu/schema/0.2/doc/oaf-0.2.html" target="_top">https://www.openaire.eu/schema/0.2/doc/oaf-0.2.html</a></td></tr></table><p>
|
|
10 |
version 0.3): </p><table border="0" summary="Simple list" class="simplelist"><tr><td><a class="link" href="https://www.openaire.eu/schema/0.3/oaf-0.3.xsd" target="_top">https://www.openaire.eu/schema/0.3/oaf-0.3.xsd</a></td></tr><tr><td><a class="link" href="https://www.openaire.eu/schema/0.3/doc/oaf-0.3.html" target="_top">https://www.openaire.eu/schema/0.3/doc/oaf-0.3.html</a></td></tr></table><p>
|
|
8 | 11 |
</p><p>The latest versions of the XML schema and documentation are also available at the following |
9 | 12 |
links: </p><table border="0" summary="Simple list" class="simplelist"><tr><td><a class="link" href="https://www.openaire.eu/schema/latest/oaf.xsd" target="_top">https://www.openaire.eu/schema/latest/oaf.xsd</a></td></tr><tr><td><a class="link" href="https://www.openaire.eu/schema/latest/doc/oaf.html" target="_top">https://www.openaire.eu/schema/latest/doc/oaf.html</a></td></tr></table><p> |
10 |
</p><p>Older versions: </p><table border="0" summary="Simple list" class="simplelist"><tr><td><a class="link" href="https://www.openaire.eu/schema/0.1/oaf-0.1.xsd" target="_top"><code class="code">oaf</code> XML |
|
11 |
schema v0.1</a></td></tr><tr><td><a class="link" href="https://www.openaire.eu/schema/0.1/doc/oaf-0.1.html" target="_top"><code class="code">oaf</code> XML schema v0.1 documentation</a></td></tr></table><p> |
|
12 |
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cha_oai_pmh"></a>Chapter 2. Bulk access via OAI-PMH</h1></div></div></div><p>OAI-PMH is a standard protocol for metadata publishing and harvesting. For details on the |
|
13 |
</p><p>Older versions: </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="code">oaf</code> v0.2 <a class="link" href="https://www.openaire.eu/schema/0.1/oaf-0.2.xsd" target="_top"> XML |
|
14 |
schema</a> and <a class="link" href="https://www.openaire.eu/schema/0.1/doc/oaf-0.2.html" target="_top">documentation</a></td></tr><tr><td><code class="code">oaf</code> v0.1 <a class="link" href="https://www.openaire.eu/schema/0.1/oaf-0.1.xsd" target="_top"> XML |
|
15 |
schema</a> and <a class="link" href="https://www.openaire.eu/schema/0.1/doc/oaf-0.1.html" target="_top">documentation</a></td></tr></table><p> |
|
16 |
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cha_oai_pmh"></a>Chapter 3. Bulk access via OAI-PMH</h1></div></div></div><p>OAI-PMH is a standard protocol for metadata publishing and harvesting. For details on the |
|
13 | 17 |
OAI-PMH protocol please refer to the official documentation at <a class="link" href="http://www.openarchives.org/OAI/openarchivesprotocol.html" target="_top">http://www.openarchives.org/OAI/openarchivesprotocol.html</a></p><p>The OpenAIRE OAI-PMH endpoint is <a class="link" href="http://api.openaire.eu/oai_pmh" target="_top">http://api.openaire.eu/oai_pmh</a></p><p>For information about the endpoint check <a class="link" href="http://api.openaire.eu/oai_pmh?verb=Identify" target="_top">http://api.openaire.eu/oai_pmh?verb=Identify</a></p><p>The updated list of OAI sets is always available at: <a class="link" href="http://api.openaire.eu/oai_pmh?verb=ListSets" target="_top">http://api.openaire.eu/oai_pmh?verb=ListSets</a></p><p>For quick reference, we report here the likely more interesting sets:</p><table border="0" summary="Simple list" class="simplelist"><tr><td>openaire: the set of publications. Metadata prefixes available: oaf, oai_dc</td></tr><tr><td>openaire_data: the set of datasets. Metadata prefixes available: oaf, |
14 | 18 |
oai_datacite</td></tr><tr><td>OpenAccess: the set of all Open Access publications and datasets. Metadata prefixes |
15 | 19 |
available: oaf (return datasets and publications), oai_dc (return datasets and |
... | ... | |
17 | 21 |
Metadata prefix available: oaf</td></tr><tr><td>WTProjects: the set of projects funded by Wellcome Trust. Metadata prefix available: |
18 | 22 |
oaf</td></tr><tr><td>organizations: the set of all organizations. Metadata prefix available: oaf</td></tr></table><p>For the list of available metadata prefixes, check: <a class="link" href="http://api.openaire.eu/oai_pmh?verb=ListMetadataFormats" target="_top">http://api.openaire.eu/oai_pmh?verb=ListMetadataFormats</a>.</p><p>Note that records will always be available in the OpenAIRE format (<a class="link" href="https://www.openaire.eu/schema/0.2/oaf-0.2.xsd" target="_top">schema</a>, <a class="link" href="https://www.openaire.eu/schema/0.2/doc/oaf-0.2.html" target="_top">documentation</a>). |
19 | 23 |
The availability of records in oai_dc and oai_datacite depends on the typology of |
20 |
records.</p><p>Publications are avaialble in oai_dc according to the <a class="link" href="https://guidelines.openaire.eu/wiki/Literature_Guidelines:_Use_of_OAI-DC" target="_top">OpenAIRE3.0 guidelines for literature repositories</a>.</p><p>Datasets are available in oai_datacite according to the <a class="link" href="https://guidelines.openaire.eu/wiki/Data_Guidelines:_Use_of_DataCite_Metadata_Schema" target="_top">OpenAIRE2.0 guidelines for data archives</a>. </p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cha_projects_http"></a>Chapter 3. Bulk access to projects</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#d0e152">DSpace/ePrints</a></span></dt><dt><span class="section"><a href="#d0e194">Projects in TSV file</a></span></dt></dl></div><p>The APIs offer custom access to metadata about projects funded by a selection of
|
|
24 |
records.</p><p>Publications are avaialble in oai_dc according to the <a class="link" href="https://guidelines.openaire.eu/wiki/Literature_Guidelines:_Use_of_OAI-DC" target="_top">OpenAIRE3.0 guidelines for literature repositories</a>.</p><p>Datasets are available in oai_datacite according to the <a class="link" href="https://guidelines.openaire.eu/wiki/Data_Guidelines:_Use_of_DataCite_Metadata_Schema" target="_top">OpenAIRE2.0 guidelines for data archives</a>. </p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cha_projects_http"></a>Chapter 4. Bulk access to projects</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#d0e181">DSpace/ePrints</a></span></dt><dt><span class="section"><a href="#d0e223">Projects in TSV file</a></span></dt></dl></div><p>The APIs offer custom access to metadata about projects funded by a selection of
|
|
21 | 25 |
international funders for the DSpace and EPrints platforms and as TSV file.</p><p><a name="fundings"></a>The currently supported funding streams and |
22 | 26 |
relative codes are: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>FP7: The 7th Framework Programme funded by the European Commission</p></li><li class="listitem"><p>WT: Wellcome Trust funding programme</p></li></ul></div><p> Coming soon: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>H2020: Horizon2020 Programme funded by the European Commission</p></li><li class="listitem"><p>FCT: the funding programme of Fundação para a Ciência e a Tecnologia, the |
23 | 27 |
national funding agency of Portugal</p></li></ul></div><p> |
24 |
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e152"></a>DSpace/ePrints</h2></div></div></div><table border="0" summary="Simple list" class="simplelist"><tr><td>DSpace endpoint: <a class="link" href="http://api.openaire.eu/projects/dspace/$fundingStream/ALL/ALL" target="_top">http://api.openaire.eu/projects/dspace/$fundingStream/ALL/ALL</a></td></tr><tr><td>ePrints endpoint: <a class="link" href="http://api.openaire.eu/projects/eprints/$fundingStream/ALL/ALL" target="_top">http://api.openaire.eu/projects/eprints/$fundingStream/ALL/ALL</a></td></tr></table><p> The URLs embed the parameters needed to collect projects funded by specific funding
|
|
28 |
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e181"></a>DSpace/ePrints</h2></div></div></div><table border="0" summary="Simple list" class="simplelist"><tr><td>DSpace endpoint: <a class="link" href="http://api.openaire.eu/projects/dspace/$fundingStream/ALL/ALL" target="_top">http://api.openaire.eu/projects/dspace/$fundingStream/ALL/ALL</a></td></tr><tr><td>ePrints endpoint: <a class="link" href="http://api.openaire.eu/projects/eprints/$fundingStream/ALL/ALL" target="_top">http://api.openaire.eu/projects/eprints/$fundingStream/ALL/ALL</a></td></tr></table><p> The URLs embed the parameters needed to collect projects funded by specific funding
|
|
25 | 29 |
stream, where the pattern is |
26 | 30 |
<code class="code">FundingStream/FundingSubStream/FundingSubSubStream</code>.</p><p>Additional parameters can be concatenated to the URL to refine the results by date |
27 | 31 |
(date must be in the form <code class="code">YYYY-MM-DD</code>): </p><table border="0" summary="Simple list" class="simplelist"><tr><td>startFrom</td></tr><tr><td>startUntil</td></tr><tr><td>endFrom</td></tr><tr><td>endUntil</td></tr></table><p>Examples: </p><table border="0" summary="Simple list" class="simplelist"><tr><td>Get Wellcome Trust projects for EPrints: <a class="link" href="http://api.openaire.eu/projects/eprints/WT/ALL/ALL" target="_top">http://api.openaire.eu/projects/eprints/WT/ALL/ALL</a></td></tr><tr><td>Get EC-FP7 projects of the specific programme “SP2-IDEAS” for EPrints: <a class="link" href="http://api.openaire.eu/projects/eprints/FP7/SP2/ALL" target="_top">http://api.openaire.eu/projects/eprints/FP7/SP2/ALL</a></td></tr><tr><td>Get EC-FP7 projects for DSpace that started after the given date: <a class="link" href="http://api.openaire.eu/projects/dspace/FP7/ALL/ALL?startFrom=2011-01-01" target="_top">http://api.openaire.eu/projects/dspace/FP7/ALL/ALL?startFrom=2011-01-01</a></td></tr></table><p> |
28 |
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e194"></a>Projects in TSV file</h2></div></div></div><p>Endpoint: <a class="link" href="http://api.openaire.eu/projects/tsv" target="_top">http://api.openaire.eu/projects/tsv</a></p><p>Mandatory parameter: </p><table border="0" summary="Simple list" class="simplelist"><tr><td>funding: the code of the funding program (See <a class="xref" href="#fundings">Funding codes</a>)</td></tr></table><p>
|
|
32 |
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e223"></a>Projects in TSV file</h2></div></div></div><p>Endpoint: <a class="link" href="http://api.openaire.eu/projects/tsv" target="_top">http://api.openaire.eu/projects/tsv</a></p><p>Mandatory parameter: </p><table border="0" summary="Simple list" class="simplelist"><tr><td>funding: the code of the funding program (See <a class="xref" href="#fundings">Funding codes</a>)</td></tr></table><p>
|
|
29 | 33 |
</p><p>Examples: </p><table border="0" summary="Simple list" class="simplelist"><tr><td>Get Wellcome Trust projects in a tsv file: <a class="link" href="http://api.openaire.eu/projects/tsv?funding=WT" target="_top">http://api.openaire.eu/projects/tsv?funding=WT</a></td></tr></table><p> The returned tsv file has an header where the semantics of each column is |
30 |
described. </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cha_http-api"></a>Chapter 4. Selective access with HTTP API</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#sec_http-common">Common API parameters</a></span></dt><dt><span class="section"><a href="#sec_http-pubs">Publications</a></span></dt><dt><span class="section"><a href="#sec_http-datasets">Datasets</a></span></dt><dt><span class="section"><a href="#sec_http-projects">Projects</a></span></dt></dl></div><p>The OpenAIRE+ HTTP API allows developers to access the metadata information space of OpenAIRE+ by
|
|
34 |
described. </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cha_http-api"></a>Chapter 5. Selective access with HTTP API</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#sec_http-common">Common API parameters</a></span></dt><dt><span class="section"><a href="#sec_http-pubs">Publications</a></span></dt><dt><span class="section"><a href="#sec_http-datasets">Datasets</a></span></dt><dt><span class="section"><a href="#sec_http-projects">Projects</a></span></dt></dl></div><p>The OpenAIRE+ HTTP API allows developers to access the metadata information space of OpenAIRE+ by
|
|
31 | 35 |
performing queries over publications, datasets, and projects.</p><p>The API is intended for metadata discovery and exploration only, that is it does not give direct access to publication files and it does not provide access |
32 | 36 |
to the whole information space: the number of total results returned by one query is limited |
33 |
to 10,000.</p><p>For accessing the whole information space, developers are encouraged to use the <a class="xref" href="#cha_oai_pmh" title="Chapter 2. Bulk access via OAI-PMH">OAI-PMH</a></p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec_http-common"></a>Common API parameters</h2></div></div></div><p> Parameters included in this section can always be specified, regardless the type of
|
|
37 |
to 10,000.</p><p>For accessing the whole information space, developers are encouraged to use the <a class="xref" href="#cha_oai_pmh" title="Chapter 3. Bulk access via OAI-PMH">OAI-PMH</a></p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec_http-common"></a>Common API parameters</h2></div></div></div><p> Parameters included in this section can always be specified, regardless the type of
|
|
34 | 38 |
entities (metadata about publications, datasets, or projects) you want to retrieve. </p><p>To query for publications metadata: |
35 | 39 |
<code class="code">http://api.openaire.eu/search/publications</code></p><p>To query for datasets metadata: <code class="code">http://api.openaire.eu/search/datasets</code></p><p>To query for projects metadata: <code class="code">http://api.openaire.eu/search/projects</code></p><div class="variablelist"><dl class="variablelist"><dt><span class="term">page</span></dt><dd><p>Page number of the search results.</p></dd><dt><span class="term">size</span></dt><dd><p>Number of results per page.</p></dd><dt><span class="term">format</span></dt><dd><p>Options:<span class="command"><strong>json | xml | csv | tsv</strong></span></p><p>Select the format of the response. Default is <span class="command"><strong>xml</strong></span>.</p></dd><dt><span class="term">model</span></dt><dd><p>Options:<span class="command"><strong>openaire | sygma</strong></span></p><p>Select the data model of the response. Default is <span class="command"><strong>openaire</strong></span>. Model |
36 | 40 |
<span class="command"><strong>sygma</strong></span> is a simplified version of the <span class="command"><strong>openaire</strong></span> |
Also available in: Unified diff
added schema 0.3 as the latest schema