Ulrichsweb is a directory of information about serials many libraries subscribe to. Evolved from the old and renowned Ulrich’s print directory of course, and now owned by Serial Solutions (a division of Proquest).
You may have the idea of incorporating some of the info about serials included in Ulrichsweb in your own services.
It turns out if you subscribe to Ulrichsweb, there is an API you are already licensed to use. The API does expose a few key pieces of data you may find useful (such as a boolean value for ‘refereed’). It sadly lacks a few things included in the Ulrichsweb directory itself that would be awfully useful (such as review text).
There is very little evidence on the web that the API even exists. A vague one-page blurb in this marketting brochure is where I noticed it, googling for ‘ulrichs api’. So I’m writing this blog post in hopes of making it easier for other library coders wondering if there’s an Ulrichs API to have some chance of discovering it on the web, and also to get some overview of what it provides, which otherwise is not clear without some back-and-forth with Serials Solutions (the current Ulrichs vendor). (How do you know if you want to spend the time on this back and forth if you don’t even know what the API will do for you?).
The API is included with your ulrichs subcription, but to get access to the documentation, you’ll have to file a support request at http://support.serialssolutions.com/app/ask asking for it. (Thanks James Van Mil on the code4lib listserv for the hint).
And once you get access to the docs, you’ll find out that to access the API, you’ll need an API key which can only be retrieved from the Serial Solutions Customer Center:
A unique, 10-digit, Search API Key is required to utilize the Search API service. This Key can be obtained through the Ulrichsweb Administration Console in the Serials Solutions Client Center. Click on the Ulrichsweb tab and go to the Search API section. The Key provided can be used for all of the Search API requests.
I’m guessing this API key is probably available for all customers even before you go through this multi-step back-and-forth to get access to the docs; so if you’re a developer who doesn’t ordinarily have access to the Client Center, and you’re going to have to ask someone else at your institution to look up the API Key for you… you might want to ask them at the same time you begin communication with SerSol support, to do this all in parallel, you know?
And of course the docs will also tell you the API URL endpoint, which I’m not going to reveal, because clearly SerialSolutions wants you to engage in a multiple-step process of interacting with support and signing the Terms before knowing that.
What the API does
It’s a pretty straightforward API, submit a query, get one or more responses back in XML or JSON (your choice). There’s also an SRU variant of the API, which only the masochistic would want to use, the straightforward ‘ordinary’ variant is quite easy to use and reasonable.
You can search by “title, issn, publisher, etc”. Yes, the docs really say “etc”, and don’t tell us what else might be included in “etc”. That’s okay, title, issn and publisher are sufficient for the sorts of uses that immediately occured to me — really mostly just ISSN is all I’d be using.
You can specify how many results you want in a response page, and page through them with a start param, etc. Since I’ll mostly be looking up by ISSN, I’d expect only one hit for each ISSN query, and that seems to work as expected.
Now, what everyone really wants to know: What does the API response tell you about each hit?
Of course, as we’ve come to expect from library vendor API documentation, the docs don’t tell us; they only give us one basic non-comprehensive example, without annotations as to what fields mean what. So we’ve got to do some exploratory requests and ‘reverse engineer’ what fields are available and what they likely mean. Some fields are only included for some hits and not others.
- unique titleID in ulrichs system
- refereed: true/false. Corresponds, of course, to the value with the same label in the ulrichs native html ui. This one is the most valuable piece of data here for my uses — something my users want to know, for which I don’t really have access to any other machine-readable sources of info.
- openAccess: true/false. This one is actually potentially pretty sweet too (and oddly, I don’t even know if/where the ulrichsweb native html ui displays this).
- reviewed: true/false. I’m not quite sure what this means. There’s no field labelled ‘reviewed’ in ulrichsweb html ui. Does it just mean whether review text exists in the ulrichsweb html ui? (review text that the api sadly does not give us, see below)
- frequency. “Monthly”, “Quarterly”, etc. If these are a controlled vocabulary, that fact and vocab are not documented, I dunno.
- description: A very brief one sentence description, matching what’s labelled ‘description’ in the ulrichsweb html api.
- subjects (??): There’s a subject key present in the response, but it was empty of data for the hits in exploratory queries I did, including for some titles that do have subjects listed in ulrichs native html ui. So I suspect the api never actually gives you these, not sure why the key is there anyway.
- languages: Potentially a list of languages? In all of the exploratory queries I did, it was either blank or “English” though. Again, if it’s a controlled vocab here, it’s not documented.
- formats: A list of zero or one. Often blank, the only examples I saw were one element, “Print”. Perhaps “Online” is the other option? (ISSNs are, technically, format-specific, so an online variant of a journal will have a different ISSN than a print variant. I think they usually have different ulrichs records too).
- serial types: Again is structured such that it can be 0 to many, but I only saw either 0 or 1, such as “Journal” or “Magazine”. Also frequently empty. It’s prob a controlled vocab, but as we expect by now, no docs of possible values here, as usual limiting utility. Note corresponding “Serial Type” label in ulrichsweb html ui.
- content types: Structured 0-to-many, but only saw 0 or 1. Including “Academic / Scholarly” and “Consumer”. Again frequently empty though. Again if it’s controlled vocab, undocumented. Note corresponding “Content Type” label in ulrichsweb html ui.
- RSS feed info!: this is potentially pretty neat, although I’d probably use the free journaltocs api for this instead. The Ulrichs api response includes some cryptic undocumented controlled values for a ‘type code’ and ‘frequency code’.
Other stuff I’m missing cause I didn’t happen to run into it in my explorations, and none of it is documented? Maybe.
Info/data that does not seem to be in API response, even though it’s included in ulrichsweb native html ui
- publisher’s URL for the title. This is dissapointing, as if you combine a title’s URL with the ‘openAccess’ boolean, it could provide a useful access route to open access journals.
- Review text. The standard web ui, for some titles, has one or several one paragraph ‘reviews’, which are usually more like short descriptions. It’s too bad that the API doesn’t provide these, they could be awfully useful — the one sentence ‘description’ that is provided is all we’ve got, not too much.
- Relationships between ulrichs records. Native ulrichs html UI gives you a wealth of title relationship info, and links from one ulrichs record to another elated title, along with labels as to the nature of the relationship. Linked online and print versions; alternate language versions; regionalized versions; former and later title changes; mergers and splits; etc. This could be quite useful info to an app, but sadly the API reveals none of it.
- common/standard short/abbreviated titles: The ulrichs native web ui lists these, and this could be quite useful data for powering lookups and citation exports in your own apps. But sadly the API doesn’t seem to reveal them. (Could lookup by abbreviated title be one of the ‘etc’ fields you can use to search the ulrichs api? I dunno, it would be useful if it were!)
- Cover images. The standard web ui does have cover images for some titles, but the API does not seem to expose these urls (like, say, the Amazon api does for it’s cover images).
It’s a great step for Serials Solutions to be including an API with every ulrichsweb license. Formerly, all they had was the “XML Data Service”, which I investigated a few years ago — it is not included in your ulrichsweb subscription, and is priced very expensively, probably for the “other vendor” market (people who will be reselling this data or a service based upon it to their own customers). That’s not what this ulrichsweb api is; the ulrichsweb api included with your subscription seems to be 1 or 2 years old, although I’m just discovering it now.
In my opinion, in this 21st century nearly every platform we license, and certainly every directory-like platform like ulrichsweb, ought to include an API at no extra cost so we can incorporate the info we’re licensing in our own library platforms at the right points of our user’s workflows — not just expose it to users as a silo’d seperate platform on the publishers website. So, good on them.
And the API does include one or two valuable data points or functions for the sorts of features and apps I provide for my library users — including, mainly, simply the ability to look up by ISSN and get a title, as well as the “referreed” true/false boolean.
However, some of the data which would be most useful, and which is included in the ulrichsweb directory standard web ui — seems to be left out of the API. I don’t know if this is intentional (they didn’t want to expose the jewels in this way, and/or license the data from upstream providers that don’t let them), or if it’s simply an oversight, they didn’t realize what the actual valuable bits were that people might want. Either way, it makes the API nice and welcome, but probably not a game changer, or something that very significantly increases the value of an ulrichs subscription to the customer. Mostly, alas, an ulrichs subscription is still to the silo’d ulrichs vendor platform, not to a source of data you can integrate into your own library web platform.