Introduction
The SHERPA/RoMEO Application Programmers' Interface (API) is a machine-to-machine interface that lets programmers access SHERPA/RoMEO data from their applications. For instance, you could use the API to incorporate an automatic look-up of a journal or publisher into your repository's deposition process.
We encourage you to play with the API and explore the potential for including it in your own repository software. Please send any suggestions and feedback either on the API itself or on the documentation to Peter Millington (romeo@sherpa.ac.uk).
Versions and Documentation
The latest version of the SHERPA/RoMEO API is Version 2.4.2. We recommend that you work with this version, because it incorporates most of the improvements from the upgrade to interactive RoMEO, released in October 2009. It also generates XML output that can be validated against its DTD.
Full technical details are available in the following documentation download:
- Version 2.4.2 Full Documentation - pdf download [134kB]
Earlier 2.* versions of SHERPA/RoMEO API will remain operational for the foreseeable future.
Note: The earliest 1.* prototype versions of the API - e.g. V.1.1 - will be switched off at the end of 2009.
Any applications using these prototypes should upgrade at the earliest opportunity. In most cases, only the root API URL needs to be changed in the application.
Recent Changes
The main changes in the latest version are:
- Journal coverage has been expanded, through addition of the DOAJ and Entrez databases.
- Journal title searches accommodate abbreviations
- ISSN queries now also handle Electronic ISSNs (ESSNs) as well as Print ISSNs
- Compliance with research funders' open access mandates can be selectively displayed for specific countries.
A full list of changes is given in Appendix D of the documentation.
How to use the API
The basic principle is that an application makes an HTTP request to the API, which returns an XML stream with the search results. The query specification is given in the URL's parameters. The main searches that are available are for journal title, ISSN and publisher's name, although there are also some special searches, such as for RoMEO colours. View the following links in your browser to see examples (which use Version 2.4).
- Publisher's name search - 'Institute of Physics':
http://www.sherpa.ac.uk/romeo/api24.php?pub=institute%20of%20physics&qtype=exact
- Journal title search - 'Journal of Geology' - Single Result:
http://www.sherpa.ac.uk/romeo/api24.php?jtitle=Journal%20of%20Geology
- Journal title search - 'Oncology Reviews' - showing compliance with the Medical Research Council (MRC) open access mandate:
http://www.sherpa.ac.uk/romeo/api24.php?jtitle=oncology%20reviews&showfunder=mrc
- Journal title search - containing 'Modern Language' - Multiple Results:
http://www.sherpa.ac.uk/romeo/api24.php?jtitle=modern%20language&qtype=contains
- ISSN - International Standard Serial Number:
http://www.sherpa.ac.uk/romeo/api24.php?issn=1444-1586
- RoMEO Colour - All 'Green' publishers (omitting 'Mandated OA' data):
http://www.sherpa.ac.uk/romeo/api24.php?colour=green&showfunder=none [expect a slow response]
- All Publishers (omitting 'Mandated OA' data):
http://www.sherpa.ac.uk/romeo/api24.php?all=yes&showfunder=none [expect a slow response]
- An Unsuccessful search (zero results) - 'Recycling Journal':
http://www.sherpa.ac.uk/romeo/api24.php?jtitle=Recycling%20Journal
- Error report from an invalid query - Search parameters missing:
http://www.sherpa.ac.uk/romeo/api24.php
Searching for Journals by Title using the API
Although it would be nice to be able to automate fully the look-up of journal publishers using the API, this may often not be possible, because a query may return zero or many results. Even if a single journal is found, it is advisable to confirm that it is indeed the correct one. We therefore recommend the following general approach to handling journal queries:
- Search by journal title, and display the title(s) found
- Get the end-user to confirm/select the correct title - even when only a single title is found.
- Retrieve and display the publisher's details (if any)
Updated: 29-Oct-2009