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 or CRIS deposition process.
We encourage you to play with the API and explore the potential for including it in your own repository and CRIS software. Please send any suggestions and feedback either on the API itself or on the documentation to Peter Millington (firstname.lastname@example.org).
Versions and Documentation
The latest version of the SHERPA/RoMEO API is Version 2.9. We recommend that you work with this version, because it incorporates the improvements from the major upgrade to interactive RoMEO released in August 2011 and susbequent enhancements. It also generates XML output that can be validated against its DTD.
The root URL for Version 2.9 of the API is:
Full technical details are available in the following documentation download:
- Version 2.9.4 Full Documentation - pdf download [752kB]
Earlier versions 2.4 and above of the SHERPA/RoMEO API will remain operational in the short term, but will be shut down in earl 2013. Any applications using these versions should be upgraded at the earliest opportunity. In most cases, only the root API URL needs to be changed in the application, although you will then need to go on to modify your applications if you wish to exploit the important new features in the latest version.
We strongly recommend that regular and heavy API users register for a free API Key. This allows you to exceed our limit of 500 requests per day and has a number of other benefits.
Recently implemented changes include:
- RoMEO now includes provisional records for certain new publishers. These are flagged by a new XML attribute
<publisher id="724" status="provisional">
- RoMEO now includes policy exceptions for certain publishers. These have their own persistent IDs, but an additional XML attribute
parentidattribute gives the persistent ID of the parent publisher record e.g.
<publisher id="1123" parentid="51">
- True REST query URLs implement for journal ISSN and RoMEO publisher IDs e.g. http://www.sherpa.ac.uk/romeo/api29/issn/1035-8811/.
- To encourage efficient usage of the API, access controls now limit the number of queries that non-registered users can submit to the API to 500 per day. This is enough for most applications, although the limit may be changed in the future. Registered users receive an access key that permits unlimited access and has other benefits.
You can register for a free API Access Key at:
There is a presentation that explains the registration process at:
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. The examples use the default XML schema for compatibility with Version 2.4. Add
&versions=all to the queries to get data using the new XML schema with separate fields for Publisher's version/PDF
- Publisher's name search - 'Institute of Physics':
Original XML schema (default) compatible with earlier versions
New XML schema with separate fields for Publisher's version/PDF
- Journal title search - 'Journal of Geology' - Single Result:
- Journal title search - 'Oncology Reviews' - showing compliance with the Medical Research Council (MRC) open access mandate:
- Journal title search - containing 'Modern Language' - Multiple Results:
- ISSN - International Standard Serial Number:
This can also be formulated as a REST query URL:
- RoMEO Colour - All 'Yellow' publishers (omitting 'Mandated OA' data):
http://www.sherpa.ac.uk/romeo/api29.php?colour=yellow&showfunder=none [expect a slow response]
- RoMEO Publisher's Record Update Date - Database records updated or or since the 1st October 2012:
- Publisher's Country - RoMEO records for Spanish publishers:
- All Publishers (omitting 'Mandated OA' data):
http://www.sherpa.ac.uk/romeo/api29.php?all=yes&showfunder=none [expect a slow response]
- An Unsuccessful search (zero results) - 'Recycling Journal':
- Error report from an invalid query - Search parameters missing:
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)
Wishes and ideas for the future enhancement of the API have been collated from a survey of SHERPA/RoMEO Application Programmers' Interface (API) users, notes from breakout sessions at the RoMEO API Workshop, Edinburgh, 1st September 2010, and subsequent feedback received from users. We have started updating the wish list, so you are invited to send us further ideas and feedback. View the API Wish List >>