|
1
|
<html><head>
|
|
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">13 November 2014</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 FP7 projects</a></span></dt><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 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 FP7 projects">FP7 projects export for DSpace and EPrints</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>The default format of delivered records is <code class="code">oaf</code> (OpenAire Format - current version 0.2):
|
|
4
|
</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>
|
|
5
|
</p><p>The latest versions of the XML schema and documentation are also available at the following links:
|
|
6
|
</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>
|
|
7
|
</p><p>Older versions:
|
|
8
|
</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 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>
|
|
9
|
</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
|
|
10
|
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>publications: the set of all publications</td></tr><tr><td>datasets: the set of all datasets</td></tr><tr><td>OpenAccess: the set of all Open Access publications and datasets</td></tr><tr><td>projects: the set of all projects</td></tr><tr><td>FP7Projects: the set of projects funded by the EC Seventh Framework Programme</td></tr><tr><td>WTProjects: the set of projects funded by Wellcome Trust</td></tr><tr><td>organizations: the set of all organizations</td></tr></table><p>For the list of available metadata prefix, 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>). </p><p>The availability of records in oai_dc depends on the typology of records. Currently
|
|
11
|
publications and datasets (records of type 'result') are available in oai_dc.</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cha_projects_http"></a>Chapter 3. Bulk access to FP7 projects</h1></div></div></div><p>The APIs offer custom access to FP7 and WT projects information for the DSpace and EPrints platforms:</p><table border="0" summary="Simple list" class="simplelist"><tr><td>DSpace endpoint: <a class="link" href="http://api.openaire.eu/projects/dspace/$funder/ALL/ALL" target="_top">http://api.openaire.eu/projects/dspace/$funder/ALL/ALL</a></td></tr><tr><td>ePrints endpoint: <a class="link" href="http://api.openaire.eu/projects/eprints/$funder/ALL/ALL" target="_top">http://api.openaire.eu/projects/eprints/$funder/ALL/ALL</a></td></tr></table><p> The URLs embed the parameters needed to collect sub-portions of the EC projects, where the
|
|
12
|
pattern is <code class="code">Funder/SpecificProgramme/ScientificArea</code>.</p><p>Additional parameters can be concatenated to the URL to refine the results by date (date
|
|
13
|
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 WT projects 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 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 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>
|
|
14
|
</p></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
|
|
15
|
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
|
|
16
|
to the whole information space: the number of total results returned by one query is limited
|
|
17
|
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
|
|
18
|
entities (metadata about publications, datasets, or projects) you want to retrieve. </p><p>To query for publications metadata:
|
|
19
|
<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</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
|
|
20
|
<span class="command"><strong>sygma</strong></span> is a simplified version of the <span class="command"><strong>openaire</strong></span>
|
|
21
|
model. For <span class="command"><strong>sygma</strong></span>, only the <span class="command"><strong>xml</strong></span> format is available.
|
|
22
|
The relative XML schema is available <a class="link" href="https://www.openaire.eu/schema/sygma/oaf_sygma_v2.1.xsd" target="_top">here</a></p></dd><dt><span class="term">sortBy</span></dt><dd><p>Select the sorting order: <code class="code">sortBy=field[,ascending|,descending]</code></p><p>For the list of sortable fields, please refer to the documentation relative to the specific type of entity you are querying for.</p></dd><dt><span class="term">hasECFunding</span></dt><dd><p>Allowed values: <code class="code">true|false</code>. If hasECFunding is true gets the
|
|
23
|
publications/datasets/projects funded by the EC. If hasECFunding is false gets the
|
|
24
|
publications/datasets/projects related to projects not funded by the EC. </p></dd><dt><span class="term">hasUKFunding</span></dt><dd><p>Allowed values: <code class="code">true|false</code>.If hasUKFunding is true gets the
|
|
25
|
publications/datasets/projects funded by the UK. If hasUKFunding is false gets the
|
|
26
|
publications/datasets/projects related to projects not funded by the UK.</p></dd><dt><span class="term">funder</span></dt><dd><p>Allowed values: <code class="code">wt|fp7|h2020</code>. Search for publications/datasets/projects
|
|
27
|
by funder.</p></dd><dt><span class="term">fundingStream</span></dt><dd><p>Search for publications/datasets/projects by funding stream.</p></dd><dt><span class="term">FP7scientificArea</span></dt><dd><p>Search for FP7 publications/datasets/projects by scientific area. </p></dd><dt><span class="term">keywords</span></dt><dd><p>Allowed values: white-space separated list of keywords.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec_http-pubs"></a>Publications</h2></div></div></div><p>Endpoint: <code class="code">http://api.openaire.eu/search/publications</code></p><div class="variablelist"><dl class="variablelist"><dt><span class="term">sortBy</span></dt><dd><p>Select the sorting order: <code class="code">sortBy=field,[ascending|descending]</code></p><p>where <code class="code">field</code> is one of: <code class="code">dateofcollection</code>, <code class="code">resultstoragedate</code>, <code class="code">resultstoragedate</code>, <code class="code">resultembargoenddate</code>, <code class="code">resultembargoendyear</code>, <code class="code">resultdateofacceptance</code>, <code class="code">resultacceptanceyear</code></p></dd><dt><span class="term">doi</span></dt><dd><p>Gets the publications with the given DOIs, if any. Allowed values: comma separated list of DOIs. Alternatevely, it is possible to repeat the paramater for each requested doi.</p></dd><dt><span class="term">openairePublicationID</span></dt><dd><p>Gets the publication with the given openaire identifier, if any. Allowed values: comma separated list of openaire identifiers. Alternatevely, it is possible to repeat the paramater for each requested identifier.</p></dd><dt><span class="term">fromDateAccepted</span></dt><dd><p>Gets the publications whose date of acceptance is greater than or equal the given date. Allowed values: date formatted as <code class="code">YYYY-MM-DD</code>.</p></dd><dt><span class="term">toDateAccepted</span></dt><dd><p>Gets the publications whose date of acceptance is less than or equal the given date. Allowed values: date formatted as <code class="code">YYYY-MM-DD</code>.</p></dd><dt><span class="term">title</span></dt><dd><p>Gets the publications whose titles contain the given list of keywords. Allowed values: white-space separated list of keywords.</p></dd><dt><span class="term">author</span></dt><dd><p>Search for publications by authors. Allowed value is a white-space separated list of names and/or surnames.</p></dd><dt><span class="term">openaireAuthorID</span></dt><dd><p>Search for publications by openaire author identifier. Allowed values: comma separated list of identifiers. Alternatevely, it is possible to repeat the paramater for each author id. In both cases, author identifiers will form a query with OR semantics.</p></dd><dt><span class="term">openaireProviderID</span></dt><dd><p>Search for publications by openaire data provider identifier. Allowed values: comma separated list of identifiers. Alternatevely, it is possible to repeat the paramater for each provider id. In both cases, provider identifiers will form a query with OR semantics.</p></dd><dt><span class="term">openaireProjectID</span></dt><dd><p>Search for publications by openaire project identifier. Allowed values: comma separated list of identifiers. Alternatevely, it is possible to repeat the paramater for each provider id. In both cases, provider identifiers will form a query with OR semantics.</p></dd><dt><span class="term">hasProject</span></dt><dd><p>Allowed values: <code class="code">true|false</code>. If hasProject is true gets the publications
|
|
28
|
that have a link to a project. If hasProject is false gets the publications with no links
|
|
29
|
to projects.</p></dd><dt><span class="term">projectID</span></dt><dd><p>Search for publications associated to a project with the given grant identifier.</p></dd><dt><span class="term">FP7ProjectID</span></dt><dd><p>Search for publications associated to a FP7 project with the given grant number. It is equivalent to a query by <code class="code">funder=FP7&projectID=grantID</code></p></dd><dt><span class="term">OA</span></dt><dd><p>Allowed values: <code class="code">true|false</code>. If OA is true gets Open Access publications.
|
|
30
|
If OA is false gets the non Open Access publications</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec_http-datasets"></a>Datasets</h2></div></div></div><p>Endpoint: <code class="code">http://api.openaire.eu/search/datasets</code></p><div class="variablelist"><dl class="variablelist"><dt><span class="term">sortBy</span></dt><dd><p>Select the sorting order: <code class="code">sortBy=field,[ascending|descending]</code></p><p>where <code class="code">field</code> is one of: <code class="code">dateofcollection</code>, <code class="code">resultstoragedate</code>, <code class="code">resultstoragedate</code>, <code class="code">resultembargoenddate</code>, <code class="code">resultembargoendyear</code>, <code class="code">resultdateofacceptance</code>, <code class="code">resultacceptanceyear</code></p></dd><dt><span class="term">doi</span></dt><dd><p>Gets the datasets with the given DOIs, if any. Allowed values: comma separated list of DOIs. Alternatevely, it is possible to repeat the paramater for each requested doi.</p></dd><dt><span class="term">openaireDatasetID</span></dt><dd><p>Gets the publication with the given openaire identifier, if any. Allowed values: comma separated list of openaire identifiers. Alternatevely, it is possible to repeat the paramater for each requested identifier.</p></dd><dt><span class="term">fromDateCollected</span></dt><dd><p>Gets the datasets whose date of acceptance is greater than or equal the given
|
|
31
|
date. Allowed values: date formatted as <code class="code">YYYY-MM-DD</code>.</p></dd><dt><span class="term">toDateCollected</span></dt><dd><p>Gets the datasets whose date of acceptance is less than or equal the given date. Allowed values: date formatted as <code class="code">YYYY-MM-DD</code>.</p></dd><dt><span class="term">title</span></dt><dd><p>Gets the datasets whose titles contain the given list of keywords. Allowed values: white-space separated list of keywords.</p></dd><dt><span class="term">author</span></dt><dd><p>Search for datasets by authors. Allowed value is a white-space separated list of names and/or surnames.</p></dd><dt><span class="term">openaireAuthorID</span></dt><dd><p>Search for datasets by openaire author identifier. Allowed values: comma separated list of identifiers. Alternatevely, it is possible to repeat the paramater for each author id. In both cases, author identifiers will form a query with OR semantics.</p></dd><dt><span class="term">openaireProviderID</span></dt><dd><p>Search for datasets by openaire data provider identifier. Allowed values: comma separated list of identifiers. Alternatevely, it is possible to repeat the paramater for each provider id. In both cases, provider identifiers will form a query with OR semantics.</p></dd><dt><span class="term">openaireProjectID</span></dt><dd><p>Search for publications by openaire project identifier. Allowed values: comma separated list of identifiers. Alternatevely, it is possible to repeat the paramater for each provider id. In both cases, provider identifiers will form a query with OR semantics.</p></dd><dt><span class="term">hasProject</span></dt><dd><p>Allowed values: <code class="code">true|false</code>. If hasProject is true gets the datasets
|
|
32
|
that have a link to a project. If hasProject is false gets the datasets with no links
|
|
33
|
to projects.</p></dd><dt><span class="term">FP7ProjectID</span></dt><dd><p>Search for datasets associated to a FP7 project with the given grant number. It is equivalent to a query by <code class="code">funder=FP7&projectID=grantID</code></p></dd><dt><span class="term">OA</span></dt><dd><p>Allowed values: <code class="code">true|false</code>. If OA is true gets Open Access datasets.
|
|
34
|
If OA is false gets the non Open Access datasets</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec_http-projects"></a>Projects</h2></div></div></div><p>Endpoint: <code class="code">http://api.openaire.eu/search/projects</code></p><div class="variablelist"><dl class="variablelist"><dt><span class="term">sortBy</span></dt><dd><p>Select the sorting order: <code class="code">sortBy=field,[ascending|descending]</code></p><p>where <code class="code">field</code> is one of: <code class="code">projectstartdate</code>, <code class="code">projectstartyear</code>, <code class="code">projectenddate</code>, <code class="code">projectendyear</code>, <code class="code">projectduration</code></p></dd><dt><span class="term">grantID</span></dt><dd><p>Gets the project with the given grant identifier, if any.</p></dd><dt><span class="term">name</span></dt><dd><p>Allowed values: white-space separated list of keywords. Gets the projects whose names contain the given list of keywords. </p></dd><dt><span class="term">acronym</span></dt><dd><p>Gets the project with the given acronym, if any. </p></dd><dt><span class="term">callID</span></dt><dd><p>Search for projects by call identifier.</p></dd><dt><span class="term">startYear</span></dt><dd><p>Allowed values: year formatted as <code class="code">YYYY</code>. Gets the projects that started in the given year. </p></dd><dt><span class="term">endYear</span></dt><dd><p>Allowed values: year formatted as <code class="code">YYYY</code>. Gets the projects that ended in the given year. </p></dd><dt><span class="term">participantCountries</span></dt><dd><p>Allowed values: comma separeted list of 2 letter country codes. Search for projects by participant countries. </p></dd><dt><span class="term">participantAcronyms</span></dt><dd><p>Allowed values: white space separeted list of acronyms of institutions. Search for projects by participant institutions. </p></dd></dl></div></div></div></div></body></html>
|