RoMEO Home | Introduction | Versions & Documentation | Recent Changes | How to use the API | Searching for Journals by Title | Wish List

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 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 (romeo@jisc.ac.uk).

Versions and Documentation

The latest version of the SHERPA/RoMEO API is Version 2.9, which generates XML output that can be validated against its DTD. Earlier versions of the API are no longer supported.

The root URL for the API is:

http://www.sherpa.ac.uk/romeo/api29.php

Full technical details are available in the following documentation download:

• Version 2.9.7 Full Documentation - pdf download [636kB]

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.

Recent Changes

Recently implemented changes include:

• All versions of the API before Version 2.9 were closed down on the 25th November 2013.
• RoMEO now includes provisional records for certain new publishers. These are flagged by a new XML attribute status – e.g. <publisher id="724" status="provisional">
• RoMEO now includes policy exceptions for certain publishers. These have their own persistent IDs, but an additional XML attribute parentid attribute 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:

  http://www.sherpa.ac.uk/romeo/apiregistry.php

  There is a presentation that explains the registration process at:

  http://www.sherpa.ac.uk/romeo/RoMEO-API-Keys-2011-10-04.pdf - pdf [1.9MB]

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.

• Publisher's name search - 'Institute of Physics':

  http://www.sherpa.ac.uk/romeo/api29.php?pub=institute%20of%20physics&qtype=exact

• Journal title search - 'Journal of Geology' - Single Result:

  http://www.sherpa.ac.uk/romeo/api29.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/api29.php?jtitle=oncology%20reviews&showfunder=mrc

• Journal title search - containing 'Modern Language' - Multiple Results:

  http://www.sherpa.ac.uk/romeo/api29.php?jtitle=modern%20language&qtype=contains

• ISSN - International Standard Serial Number:

  http://www.sherpa.ac.uk/romeo/api29.php?issn=1444-1586

  This can also be formulated as a REST query URL:

  http://www.sherpa.ac.uk/romeo/api29/issn/1444-1586/

• 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:

  http://www.sherpa.ac.uk/romeo/api29.php?pdate=2012-10-01

• Publisher's Country - RoMEO records for Spanish publishers:

  http://www.sherpa.ac.uk/romeo/api29.php?country=es

• 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':

  http://www.sherpa.ac.uk/romeo/api29.php?jtitle=Recycling%20Journal

• Error report from an invalid query - Search parameters missing:

  http://www.sherpa.ac.uk/romeo/api29.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:

1. Search by journal title, and display the title(s) found
2. Get the end-user to confirm/select the correct title - even when only a single title is found.
3. Retrieve and display the publisher's details (if any)

Wish List

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 >>

Updated: 25-Nov-2013