Ulrichsweb API

API Version 1.0
Documentation Updated: 1 March 2013

Table of Contents

Overview

Ulrichsweb Search API

1. Obtain the Unique Search Key
2. Formulate the URI Syntax
       Example URLs
3. Submit the URI request to Ulrichsweb
4. Handle the Results
       XML Result Example
       JSON/JSONP Examples

Ulrichsweb SRU Search API

1. Obtain the Unique Search Key
2. Formulate the URI Syntax
       SearchRetrieve Operation
       Explain Operation
       Example URLs
3. Submit the URI request
4. Handle the Diagnostic XML Response
5. Handle the Dublin Core XML Response

List of Available Fields for Query and Output

1. XML or JSON/JSONP Output
2. Dublin Core (DC) XML Output

For more information or Search API-specific questions, please use the Ask a Question feature in the Serials Solutions Support Center, or send an email.

Overview

The Ulrichsweb API has two versions. The API may be used to return results in (1) either XML or JSON/JSONP formats or (2) to search using the Search/Retrieval via URL (SRU) standard version 1.2 to provide diagnostic XML data that can be formatted as results in Dublin Core format. The purpose of this document is to outline both versions of the API, labeled Ulrichsweb Search API and Ulrichsweb SRU Search API, respectively.

Ulrichsweb Search API

The Ulrichsweb Search API is a simple, HTTP-based service that provides an interface for programmatic searching of the Ulrichsweb™ Global Serials Directory and will return results in raw XML or JSON/JSONP formats. The Ulrichsweb Search API can be utilized with four steps:

1. Obtain the unique Search Key
2. Formulate the URI Syntax
3. Submit the URI request to Ulrichsweb
4. Handle the results

Step 1: Obtain the Unique Search Key

Step 2: Formulate the URI Syntax

The basic URI structure is as follows:

http://ulrichsweb.serialssolutions.com/api/<SEARCHAPI_KEY>/search?<SEARCH_QUERY>

where <SEARCHAPI_KEY> is the unique, 10-digit Key for your institution, and <SEARCH_QUERY> is in the following form:

query=<FIELD>:<TERM>&sortIndex=<FIELD>&sortOrder=<ORDER>&start=<NUM>&rows=<NUM>

The first section of <SEARCH_QUERY> is required:

query=<FIELD>:<TERM>

<FIELD> can be "title", "issn", "publisher", or other available field, without quotation marks.
<TERM> is the term (value or text) you are searching for in the <FIELD>.

The rest of <SEARCH_QUERY> is optional:

sortIndex=<FIELD> -- The field to sort by. <FIELD> can be "title", "issn", "publisher", or other available field, without quotation marks.

sortOrder=<ORDER> -- The order in which the sortIndex is sorted. <ORDER> can be "asc" or "desc" (ascending or descending).

start=<NUM> -- The record number at the start of the result set. <NUM> must be a positive integer.

rows=<NUM> -- The number of records to be returned (default: 10, max: 50). <NUM> must be a an integer between 1 and 50.

Example URLs:

1. Get first 10 records where title contains "garden" and SearchAPIKey is: WYYIWQF9EF:
   http://ulrichsweb.serialssolutions.com/api/WYYIWQF9EF/search?query=title:garden
2. Get next 10 records:
   http://ulrichsweb.serialssolutions.com/api/WYYIWQF9EF/search?query=title:garden&start=10
3. Get first 50 records:
   http://ulrichsweb.serialssolutions.com/api/WYYIWQF9EF/search?query=title:garden&rows=50
4. Get first 10 records, sorted in descending order by title:
   http://ulrichsweb.serialssolutions.com/api/WYYIWQF9EF/search?query=title:garden&sortIndex=title&sortOrder=desc

Step 3: Submit the URI request to Ulrichsweb<

Query requests are submitted via HTTP GET along with an acceptable HTTP Accept request-header field (accept=application/json or accept=application/xml).

Step 4: Handle the Results

Depending on the media type specified in the HTTP accept request-header, the response will either be in XML or JSON/JSONP. The JSONP data is wrapped in a callback function called UlrichsWebJSON.

The following are the results fields:

status - Success | Error
statusMessage- [in the case of an Error, this will contain a diagnostic message]
totalRecords - [the total number of Records found for the given query]
numberOfRecords - [the number of Record returned]
requestQuery - [the query]
results - [Ulrich titles]
UlrichTitle - [Ulrich Title data]

XML Result Example

<?xml version='1.0' encoding='utf-8'?>
<searchResults>
  <status>Success</status>
  <totalRecords>762</totalRecords>
  <numberOfRecords>1</numberOfRecords>
  <requestQuery>title:garden</requestQuery>
  <requestRows>1</requestRows>
  <results>
    <UlrichTitle>
      <id>43049</id>
      <title>The Garden</title>
      <issn>1754-5897</issn>
      <refereed>false</refereed>
      <openAccess>false</openAccess>
      <reviewed>false</reviewed>
      <subject/>
      <languages/>
      <formats/>
      <serialTypes/>
      <contentTypes/>
      <rss/>
    </UlrichTitle>
  </results>
</searchResults>

JSON/JSONP Examples

UlrichsWebJSON({"searchResults":{"status":"Success","totalRecords":762,"numberOfRecords":1,"requestQuery":"title:garden","requestRows":1,"results":[{"UlrichTitle":{"id":43049,"title":"The Garden","issn":"1754-5897","refereed":false,"openAccess":false,"reviewed":false,"subject":[""],"languages":[""],"formats":[""],"serialTypes":[""],"contentTypes":[""],"rss":[""]}}]}})

 

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
  <script>
    $.ajax({
     dataType: 'jsonp',
     jsonp: 'callback',
    url: 'http://ulrichsweb.serialssolutions.com/api/json/SEARCHAPI_KEY/search?callback=?&query=title:garden',
    success: function (data) {
      alert(data.results[0].title);
    },
  });
  </script>
</body>
</html>

Ulrichsweb SRU Search API

Step 1: Obtain the Unique Search Key

A unique, 10-digit, API Key is required to utilize the Ulrichsweb Search API service. This Key is issued to authorized institutions by Serials Solutions. The API Key can be used for all of the Search API requests. Your unique Key will be stored in your institution’s Ulrichsweb Administration Console in the Serials Solutions Client Center.

Step 2: Formulate the URI Syntax

The basic URI structure is as follows:

http://ulrichsweb.serialssolutions.com/sru/<SEARCHAPI_KEY>/?<SEARCH_QUERY>

where <SEARCHAPI_KEY> is the unique, 10-digit key obtained through the instructions above, and <SEARCH_QUERY> is either a searchRetrive request or an explain request.

• SearchRetrieve Operation
  The searchRetrieve operation is based on the standard defined here:
  http://www.loc.gov/standards/sru/specs/search-retrieve.html
  
  Request Parameters
  Ulrich SRU Search API supports the all mandatory parameters as well as the optional startRecord and maximumRecords parameters. The other optional parameters are not currently supported.
  
  CQL
  Search queries must be formulated using the Contextual Query Language (CQL) specified here:
  http://www.loc.gov/standards/sru/specs/cql.html
  The Ulrich SRU Search API conforms to Level 1 of the CQL Base Profile.
  
  
• Explain Operation
  Ulrich SRU Search API supports the explain operation to meet conformance. The explain operation is specified here:
  http://www.loc.gov/standards/sru/specs/explain.html

Example URLs

1. Get first 10 records where title contains "garden" and SearchAPIKey is: WYYIWQF9EF:
   http://ulrichsweb.serialssolutions.com/sru/WYYIWQF9EF/?version=1.2&operation=searchRetrieve&query=garden&maximumRecords=10
2. Get next 10 records:
   http://ulrichsweb.serialssolutions.com/SRU/WYYIWQF9EF/?version=1.2&operation=searchRetrieve&query=garden&maximumRecords=10&startRecord=11
3. Request an explain operation:
   http:// ulrichsweb.serialssolutions.com/sru/WYYIWQF9EF

Step 3: Submit the URI Request

Query requests are submitted via HTTP GET.

Step 4: Handle the Diagnostic XML Response

Diagnostics are specified here:
http://www.loc.gov/standards/sru/specs/diagnostics.html

Step 5: Handle the Dublin Core XML Response

Ulrich SRU Search API returns the search response as Dublin Core XML packaged in an SRU XML response.

Link to SRU Records XML:
http://www.loc.gov/standards/sru/specs/search-retrieve.html#records

SRU Result Example

<?xml version='1.0' encoding='utf-8'?>
<searchRetrieveResponse xmlns="http://www.loc.gov/zing/srw/">
  <version>1.2</version>
  <numberOfRecords>844</numberOfRecords>
  <records>
    <record xmlns:dc="info:srw/schema/1/dc-v1.1">
      <recordPacking>xml</recordPacking>
      <recordPosition>1</recordPosition>
      <recordData>
        <dc:title>The Garden</dc:title>
      </recordData>
      </record>
    <record xmlns:dc="info:srw/schema/1/dc-v1.1">
      <recordPacking>xml</recordPacking>
      <recordPosition>2</recordPosition>
      <recordData>
        <dc:title>The Garden</dc:title>
        <dc:publisher>Royal Horticultural Society</dc:publisher>
        <dc:subject>GARDENING AND HORTICULTURE</dc:subject>
        <dc:language>English</dc:language>
        <dc:format>Print</dc:format>
        <dc:type>Magazine</dc:type>
      </recordData>
    </record>
    <record xmlns:dc="info:srw/schema/1/dc-v1.1">
      <recordPacking>xml</recordPacking>
      <recordPosition>3</recordPosition>
      <recordData>
        <dc:title>Gardening</dc:title>
        <dc:publisher>Scrambling Press</dc:publisher>
        <dc:subject>GARDENING AND HORTICULTURE</dc:subject>
        <dc:language>English</dc:language>
        <dc:format>Print</dc:format>
      </recordData>
    </record>
    <record xmlns:dc="info:srw/schema/1/dc-v1.1">
      <recordPacking>xml</recordPacking>
      <recordPosition>4</recordPosition>
      <recordData>
        <dc:title>Garden</dc:title>
        <dc:publisher>Paradise Production</dc:publisher>
        <dc:subject>CHILDREN AND YOUTH (FOR)</dc:subject>
        <dc:language>English</dc:language>
        <dc:format>Print</dc:format>
        <dc:type>Magazine</dc:type>
      </recordData>
    </record>
    <record xmlns:dc="info:srw/schema/1/dc-v1.1">
      <recordPacking>xml</recordPacking>
      <recordPosition>5</recordPosition>
      <recordData>
        <dc:title>The Gardener</dc:title>
        <dc:publisher>Lonehill Trading Ltd.</dc:publisher>
        <dc:subject>GARDENING AND HORTICULTURE</dc:subject>
        <dc:language>English</dc:language>
        <dc:format>Print</dc:format>
        <dc:type>Magazine</dc:type>
      </recordData>
    </record>
  </records>
  <nextRecordPosition>6</nextRecordPosition>
</searchRetrieveResponse>

List of Available Fields for Query and Output

Where present for an individual title, the metadata elements noted below are returned in the Ulrichsweb API output. Metadata elements are related to Ulrichsweb Search Results screen column headings, Search Results screen facets, Advanced Search limiters, and field labels from the Title Details view.

Selected elements are expressed as true/false values. Controlled vocabulary is used within specific fields.

XML or JSON/JSONP Output

Dublin Core (DC) XML Output

Copyright ©2013 Serials Solutions. All rights reserved.