OpenAIRE API documentation

18 January 2016


Table of Contents

1. Overview
2. Bulk access via OAI-PMH
3. Bulk access to projects
DSpace/ePrints
4. Selective access with HTTP API
Common API parameters
Publications
Datasets
Projects

Chapter 1. Overview

The OpenAIRE API allows developers to access the metadata information space of OpenAIRE programmatically.

The default format of delivered records is oaf (OpenAire Format - current version 0.3):

https://www.openaire.eu/schema/0.3/oaf-0.3.xsd
https://www.openaire.eu/schema/0.3/doc/oaf-0.3.html

The latest versions of the XML schema and documentation are also available at the following links:

https://www.openaire.eu/schema/latest/oaf.xsd
https://www.openaire.eu/schema/latest/doc/oaf.html

Older versions:

oaf v0.2 XML schema and documentation
oaf v0.1 XML schema and documentation

Chapter 2. Bulk access via OAI-PMH

OAI-PMH is a standard protocol for metadata publishing and harvesting. For details on the OAI-PMH protocol please refer to the official documentation at http://www.openarchives.org/OAI/openarchivesprotocol.html

The OpenAIRE OAI-PMH endpoint is http://api.openaire.eu/oai_pmh

For information about the endpoint check http://api.openaire.eu/oai_pmh?verb=Identify

The updated list of OAI sets is always available at: http://api.openaire.eu/oai_pmh?verb=ListSets

For quick reference, we report here the likely more interesting sets:

openaire: the set of publications. Metadata prefixes available: oaf, oai_dc
FP7Publications: the set of publications funded by EC FP7. Metadata prefixes available: oaf, oai_dc
openaire_data: the set of datasets. Metadata prefixes available: oaf, oai_datacite
OpenAccess: the set of all Open Access publications and datasets. Metadata prefixes available: oaf (return datasets and publications), oai_dc (return datasets and publications), oai_datacite (return datasets only)
projects: the set of all projects. Metadata prefix available: oaf
FP7Projects: the set of projects funded by the EC Seventh Framework Programme. Metadata prefix available: oaf
WTProjects: the set of projects funded by Wellcome Trust. Metadata prefix available: oaf

For the list of available metadata prefixes, check: http://api.openaire.eu/oai_pmh?verb=ListMetadataFormats.

Note that records will always be available in the OpenAIRE format (schema, documentation). The availability of records in oai_dc and oai_datacite depends on the typology of records.

Publications are avaialble in oai_dc according to the OpenAIRE3.0 guidelines for literature repositories.

Datasets are available in oai_datacite according to the OpenAIRE2.0 guidelines for data archives.

Chapter 3. Bulk access to projects

Table of Contents

DSpace/ePrints

The APIs offer custom access to metadata about projects funded by a selection of international funders for the DSpace and EPrints platforms.

The currently supported funding streams and relative codes are:

  • FP7: The 7th Framework Programme funded by the European Commission

  • WT: Wellcome Trust funding programme

  • H2020: Horizon2020 Programme funded by the European Commission

  • FCT: the funding programme of Fundação para a Ciência e a Tecnologia, the national funding agency of Portugal

  • ARC: the funding programme of the Australian Research Council

  • NHMRC: the funding programme of the Australian National Health and Medical Research Council

Coming soon:

  • SFI: Science Foundation Ireland

  • CSF: Croatian Science Foundation

  • MSES: Ministry of Science, Education and Sports of the Republic of Croatia

DSpace/ePrints

DSpace endpoint: http://api.openaire.eu/projects/dspace/$fundingStream/ALL/ALL
ePrints endpoint: http://api.openaire.eu/projects/eprints/$fundingStream/ALL/ALL

The URLs embed the parameters needed to collect projects funded by specific funding stream, where the pattern is FundingStream/FundingSubStream/FundingSubSubStream.

Additional parameters can be concatenated to the URL to refine the results by date (date must be in the form YYYY-MM-DD):

startFrom
startUntil
endFrom
endUntil

Examples:

Get Wellcome Trust projects for EPrints: http://api.openaire.eu/projects/eprints/WT/ALL/ALL
Get EC-FP7 projects of the specific programme “SP2-IDEAS” for EPrints: http://api.openaire.eu/projects/eprints/FP7/SP2/ALL
Get EC-FP7 projects for DSpace that started after the given date: http://api.openaire.eu/projects/dspace/FP7/ALL/ALL?startFrom=2011-01-01

Chapter 4. Selective access with HTTP API

The OpenAIRE+ HTTP API allows developers to access the metadata information space of OpenAIRE+ by performing queries over publications, datasets, and projects.

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 to the whole information space: the number of total results returned by one query is limited to 10,000.

For accessing the whole information space, developers are encouraged to use the OAI-PMH

Common API parameters

Parameters included in this section can always be specified, regardless the type of entities (metadata about publications, datasets, or projects) you want to retrieve.

To query for publications metadata: http://api.openaire.eu/search/publications

To query for datasets metadata: http://api.openaire.eu/search/datasets

To query for projects metadata: http://api.openaire.eu/search/projects

page

Page number of the search results.

size

Number of results per page.

format

Options:json | xml | csv | tsv

Select the format of the response. Default is xml.

model

Options:openaire | sygma

Select the data model of the response. Default is openaire. Model sygma is a simplified version of the openaire model. For sygma, only the xml format is available. The relative XML schema is available here

sortBy

Select the sorting order: sortBy=field[,ascending|,descending]

For the list of sortable fields, please refer to the documentation relative to the specific type of entity you are querying for.

hasECFunding

Allowed values: true|false. If hasECFunding is true gets the publications/datasets/projects funded by the EC. If hasECFunding is false gets the publications/datasets/projects related to projects not funded by the EC.

hasUKFunding

Allowed values: true|false.If hasUKFunding is true gets the publications/datasets/projects funded by the UK. If hasUKFunding is false gets the publications/datasets/projects related to projects not funded by the UK.

funder

Allowed values: wt|fp7|h2020. Search for publications/datasets/projects by funder.

fundingStream

Search for publications/datasets/projects by funding stream.

FP7scientificArea

Search for FP7 publications/datasets/projects by scientific area.

keywords

Allowed values: white-space separated list of keywords.

Publications

Endpoint: http://api.openaire.eu/search/publications

sortBy

Select the sorting order: sortBy=field,[ascending|descending]

where field is one of: dateofcollection, resultstoragedate, resultstoragedate, resultembargoenddate, resultembargoendyear, resultdateofacceptance, resultacceptanceyear

doi

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.

openairePublicationID

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.

fromDateAccepted

Gets the publications whose date of acceptance is greater than or equal the given date. Allowed values: date formatted as YYYY-MM-DD.

toDateAccepted

Gets the publications whose date of acceptance is less than or equal the given date. Allowed values: date formatted as YYYY-MM-DD.

title

Gets the publications whose titles contain the given list of keywords. Allowed values: white-space separated list of keywords.

author

Search for publications by authors. Allowed value is a white-space separated list of names and/or surnames.

openaireAuthorID

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.

openaireProviderID

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.

openaireProjectID

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.

hasProject

Allowed values: true|false. If hasProject is true gets the publications that have a link to a project. If hasProject is false gets the publications with no links to projects.

projectID

Search for publications associated to a project with the given grant identifier.

FP7ProjectID

Search for publications associated to a FP7 project with the given grant number. It is equivalent to a query by funder=FP7&projectID=grantID

OA

Allowed values: true|false. If OA is true gets Open Access publications. If OA is false gets the non Open Access publications

Datasets

Endpoint: http://api.openaire.eu/search/datasets

sortBy

Select the sorting order: sortBy=field,[ascending|descending]

where field is one of: dateofcollection, resultstoragedate, resultstoragedate, resultembargoenddate, resultembargoendyear, resultdateofacceptance, resultacceptanceyear

doi

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.

openaireDatasetID

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.

fromDateCollected

Gets the datasets whose date of acceptance is greater than or equal the given date. Allowed values: date formatted as YYYY-MM-DD.

toDateCollected

Gets the datasets whose date of acceptance is less than or equal the given date. Allowed values: date formatted as YYYY-MM-DD.

title

Gets the datasets whose titles contain the given list of keywords. Allowed values: white-space separated list of keywords.

author

Search for datasets by authors. Allowed value is a white-space separated list of names and/or surnames.

openaireAuthorID

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.

openaireProviderID

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.

openaireProjectID

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.

hasProject

Allowed values: true|false. If hasProject is true gets the datasets that have a link to a project. If hasProject is false gets the datasets with no links to projects.

FP7ProjectID

Search for datasets associated to a FP7 project with the given grant number. It is equivalent to a query by funder=FP7&projectID=grantID

OA

Allowed values: true|false. If OA is true gets Open Access datasets. If OA is false gets the non Open Access datasets

Projects

Endpoint: http://api.openaire.eu/search/projects

sortBy

Select the sorting order: sortBy=field,[ascending|descending]

where field is one of: projectstartdate, projectstartyear, projectenddate, projectendyear, projectduration

grantID

Gets the project with the given grant identifier, if any.

name

Allowed values: white-space separated list of keywords. Gets the projects whose names contain the given list of keywords.

acronym

Gets the project with the given acronym, if any.

callID

Search for projects by call identifier.

startYear

Allowed values: year formatted as YYYY. Gets the projects that started in the given year.

endYear

Allowed values: year formatted as YYYY. Gets the projects that ended in the given year.

participantCountries

Allowed values: comma separeted list of 2 letter country codes. Search for projects by participant countries.

participantAcronyms

Allowed values: white space separeted list of acronyms of institutions. Search for projects by participant institutions.