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 upgrade to interactive RoMEO released in August 2011. 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.4.2 Full Documentation - pdf download [134kB] - This is still valid, but remember to use the new Root URL for V.2.9
- Version 2.9.1 Addendum Supplement - new features - pdf download [34kB]
Earlier versions 2.4 and above of the SHERPA/RoMEO API will remain operational for the foreseeable future. However, any applications using these versions should be upgraded at the earliest opportunity. In most cases, only the root API URL initially needs to be changed in the application, although you will then need to go on to modify your applications if yo wish to exploit the new features in the latest version.
The main changes in the latest Version 2.9 are:
- Journal searches are run against the RoMEO Journals database in addition to the original Zetoc, DOAJ and Entrez databases. This means there is coverage of more journals, and more accurate identification of copyright holders.
- The default
&qtype=for journal title searches has been changed to
EXACTfor more efficient searching.
(The former default -
STARTS- is less efficient and likely to find multiple titles.)
- A new query option
?pdate=allows you to search for all RoMEO publisher records updated on or since the specified date. Dates should use the following fixed length year-month-day format - e.g.
- A new optional
&versions=allargument allows to return data that includes separate information for the publisher’s version/PDF.
- A new optional
&la=argument allows you return data in languages other than English - currenty German, Portuguese or Spanish.
- To encourage efficient usage of the API, new access controls 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:
- RoMEO Colour - All 'Green' publishers (omitting 'Mandated OA' data):
http://www.sherpa.ac.uk/romeo/api29.php?colour=green&showfunder=none [expect a slow response]
- RoMEO Publisher's Record Update Date - Database records updated or or since the 1st October 2011:
- 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. You are invited to send us further ideas and feedback. View the API Wish List >>