Skip to main content
ExLibris

Knowledge Assistant

BETA
  • Subscribe by RSS
    • Back
    Ulrich's

     

    Ex Libris Knowledge Center

    Ulrichsweb: Using the Ulrichsweb API

    1. Last updated
    2. Save as PDF

    • Product: Ulrichs

    How do I use the Ulrichsweb API?

    You must have a current Ulrichsweb API Terms of Use Non-Disclosure Agreement (NDA) on file with ProQuest. The 360 Services: XML APIs page identifies and describes the operation of APIs and our services. If you want to implement the Ulrichsweb API at your institution please use the Ex Libris Support Portal (available from the More Sites drop-down menu above) so that our Support Team can assist.

    Ulrichsweb API

    API Version 2.0

    Documentation Updated: 2 August 2018

    Go to detailed documentation in Swagger: http://ulrichsweb.serialssolutions.com/api-ui.html

    Go to this documentation in the Ex Libris Developer Network: http://developers.exlibrisgroup.com

     

    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

    A unique, 10-digit, API Key is required to utilize the Ulrichsweb Search API service. This Key is issued to authorized institutions by Ex Libris. 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 Client Center.

    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>&filterQuery=<FIELD:<TERM>&sortIndex=<FIELD>&sortOrder=<ORDER>&start=<NUM>&rows=<NUM>

    The first section of <SEARCH_QUERY> is required:

    query=<FIELD>:<TERM>

    The rest of <SEARCH_QUERY> is optional:

    • filterQuery=<FIELD>:<TERM> -- The field to filter by. <FIELD> can be any of the filter fields in List of Available Fields for Query and Output.

    • sortIndex=<FIELD> -- The field to sort by. <FIELD> can be any of the search fields in List of Available Fields for Query and Output.

    • 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 (default: 0). <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

    5. Get first 10 records where title contains populism and results are filtered to refereed titles only:

       http://ulrichsweb.serialssolutions.com/api/WYYIWQF9EF/search?query=title:populism&filterQuery=refereed:true

    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).
    HTTP POST is recommended for advanced searches where TERMS are combined (for example, Boolean searches).

    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 Records returned]
    requestQuery - [the query]
    requestFilterQuery - [the filter query]
    results - [Ulrich's titles]
    UlrichTitle - [Ulrich's Title data]

    XML Result Example

     <?xml version='1.0' encoding='utf-8'?>
<searchResults>
 <status>Success</status>
 <totalRecords>81</totalRecords>
 <numberOfRecords>1</numberOfRecords>
 <requestQuery>title:populism</requestQuery>
 <requestFilterQuery>refereed:true</requestFilterQuery>
 <requestRows>1</requestRows>
 <results>
 <UlrichTitle>
 <id>765207</id>
 <titleId>815590</titleId>
 <title>Populism</title>
 <issn>2588-8064</issn>
 <publisher>
     <string>Brill</string>
 </publisher>
 <country>Netherlands</country>
 <countryCode>NLD</countryCode>
 <status>Forthcoming</status>
 <toc>false</toc>
 <refereed>true</refereed>
 <availableOnline>false</availableOnline>
 <openAccess>false</openAccess>
 <reviewed>false</reviewed>
 <historicTitle>false</historicTitle>
 <frequency>Semi-annually</frequency>
 <price>USD 240.00</price>
 <subject>
     <string>POLITICAL SCIENCE</string>
 </subject>
 <keyFeatures>
     <string>RPR</string>
     <string>URL</string> 
 </keyFeatures>
 <otherFeatures/>
 <deweyNumbers>
     <string>320</string>
 </deweyNumbers>
 <languages>
     <string>English</string>
 </languages>
 <formats>
     <string>Print</string>
 </formats>
 <serialTypes>
     <string>Journal</string>
 </serialTypes>
 <contentTypes>
     <string>Academic / Scholarly</string>
 </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

    The Ulrichsweb SRU Search API is a service that provides an interface for programmatic searching of the Ulrichsweb Global Serials Directory using the Search/Retrieval via URL (SRU) standard version 1.2, and provides diagnostic XML data and format results in the Dublin Core format outlined here.

    The Ulrichsweb SRU Search API meets conformance to the SRU base profile. Users of this API should be familiar with SRU, CQL as well as the Dublin Core Metadata Element Set.

    The Ulrichsweb SRU 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 Dublin Core XML or Diagnostic XML results.

    5. Handle the Dublin Core XML Response.

    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 Ex Libris. 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 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.

      • Request Parameters
        The Ulrichsweb 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.
        The Ulrichsweb SRU Search API conforms to Level 1 of the CQL Base Profile.

    • Explain Operation
      The Ulrichsweb SRU Search API supports the explain operation to meet conformance. The explain operation is specified here.

    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.

    Step 5: Handle the Dublin Core XML Response

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

    Link to SRU Records XML.

    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

    The following table describes the fields that are available for query, filter, and output. Where present for an individual title, the metadata elements noted below are returned in the Ulrichsweb API output. Every field is not present for each record in Ulrichsweb. Metadata elements shown in the table below 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 and are noted in the table below.

    XML or JSON/JSONP Output

    Output Description Search_Query <FIELD> FilterQuery <FIELD> FilterQuery <TERM> Notes

    id

    System identifier for the individual serial (Do not confuse with titleId)

    		      

     

    country

    Country of publication

    country

    country_description

    country

    ISO Country Code

    Text

    e.g., DNK

    e.g., Denmark

    description

    Text describing what the serial is about

    		      

     

    subject

    Ulrich's subject classification(s)

    subject_keyword

    		    

     

    formats

    Controlled vocabulary term(s) denoting the Format edition(s) in which the serial is available.

    format

    format

    Audio

    Braille

    CD-ROM

    Email

    LargeType

    LooseLeaf

    Microform

    Online

    Print

    Video

     

    status

    Controlled vocabulary term denoting the Publication Status of the serial

    status

    status

    A

    C

    R

    M

    S

    ANP

    AFP

    Codes and their text equivalents:

    A = Active

    C = Ceased

    R = Researched / Unresolved

    M = Merged / Incorporated

    S = Suspended

    ANP = Announced Never Published

    AFP = Announced For Publication

    title

    The preferred title of the serial

    title

    		    

    Text

    titleId

    Unique Ulrich's identifier for the title of the serial (Do not confuse with id)

    titleId

    		    

    Numeric

    alt_title

    Variant titles by which the serial is known.

    alt_title

    		    

    Text

    Searches for Variant titles: Alternate Title, Parallel Language Title, MEDLINE Abbreviation, or Abbreviated Title

    spell

    Any title by which the serial is known.

    spell

    		    

    Text

    Searches for both Preferred and Variant titles

    ISSN

    International Standard Serial Number of the format edition

    issn

    		    

    Hyphenated, with check-digit

    NNNN-NNNN

    NNNN-NNNX

    publisher

    Name of commercial publisher of the serial

    publisher

    		    

    Text

    startYear

    Year of first publication

    		      

    YYYY

    frequency

    Controlled vocabulary term denoting the Frequency of publication

    		    

    Annual

    Biennial

    Bi-monthly

    Continuously

    Daily

    Fortnightly

    Irregular

    Monthly

    Other

    Quarterly

    Semi-annually

    Semi-monthly

    Triennial

    Weekly

     

    languages

    Language(s) in which the text of the serial is available

    		      

    Text

    coden

    Alphanumeric code independently assigned by the Chemical Abstracts Service that uniquely identifies a serial, mainly for use on scientific and technical serials

    coden

    		    

    e.g., SCIQDX

    otherFeatures

    Translatable codes representing additional feature(s) of the serial

    other_feature

    other_feature

    ADI

    BIA

    BV

    BIB

    BRI

    CHI

    DRI

    FRI

    FSI

    ILI

    ITA

    MAP

    MKT

    MRI

    PAT

    PRI

    RRI

    RPSA

    RVI

    SWRI

    STAT

    TRI

    TRL

    VRI

    WRI

    Codes and their text equivalents:

    ADI = Advertising included

    BIA = Back issues available

    BV = Base volumes

    BIB = Bibliographies included

    BRI = Book reviews included

    CHI = Charts included

    DRI = Dance reviews included

    FRI = Film reviews included

    FSI = Free sample available

    ILI = Illustrations included

    ITA = Index to Articles

    MAP = Maps included

    MKT = Market prices

    MRI = Music reviews included

    PAT = Patents

    PRI = Theater/Play reviews included

    RRI = Recording reviews included

    RPSA = Reprint available

    RVI = Reviews included (any)

    SWRI = Software reviews included

    STAT = Statistics

    TRI = Television reviews included

    TRL = Trade literature

    VRI = Video reviews included

    WRI = Website reviews included

    serialTypes

    Controlled vocabulary term(s) denoting the type(s) of serial

    serial_type

    serial_type

    Abstract/Index

    Bulletin

    Catalog

    Database

    Directory

    Handbook/Manual

    Journal

    Magazine

    Monographic series

    Newsletter

    Newspaper

    Proceedings

    Report

    Yearbook

     

    deweyNumbers

    Dewey Decimal Number(s) for the serial

    		      

     

    lcnumber

    Library of Classification Number for the serial

    		      

     

    price

    Publisher-reported list price for the serial

    		      

    ISO Currency Code followed by publisher's list price for institutions

    toc

    Indication of whether the serial displays Tables of Contents in Ulrichsweb

    		      

    true

    false

    historicTitle

    Indication of whether the title is a former title of the serial (i.e., not the current title)

    		      

    true

    false

    refereed

    Indication of whether the serial is Refereed/peer-reviewed

    refereed

    refereed

    true

    true

    false

    availableOnline

    Indication of whether the serial is available in an online format

    		      

    true

    false

    openAccess

    Indication of whether the serial is available via Open Access

    open_access

    open_access

    true

    true

    false

    openAccessUrl

    If serial is Open Access, the Open Access URL for the serial

     

    		    

     

    reviewed

    Indication of whether the serial has a review in the Ulrich s record

    		      

    true

    false

    contentTypes

    Controlled vocabulary term(s) denoting the primary target audience(s) of the serial

    content_type

    content_type

    Academic/Scholarly

    Bibliography

    Consumer

    Government

    Trade

     

    keyFeatures

    Translatable codes representing key features Ulrich's notes for the serial

    key_feature

    key_feature

    RPR

    AVO

    AI

    EON

    OPA

    MLR

    TOC

    RSS

    URL

    JCR

    CCC

    Codes and their text equivalents:

    RPR = Refereed/Peer-reviewed

    AVO = Available Online

    AI = Abstracted or Indexed

    EON = Electronic-only

    OPA = Open Access

    MLR = Magazines for Libraries review (has)

    TOC = Table of Contents (has)

    RSS = RSS Availability

    URL = Website URL

    JCR = Journal Citation Reports

    CCC = Copyright Clearance Center (CCC)

    rss

    Type, frequency, source, description and URL of RSS feed available for the serial

    		      

     

    rssTypeCode

    Translatable code denoting the type of RSS feed

    		      

    Codes and their text equivalents:

    AA = Article Alert

    FI = Forthcoming Issues

    LI = Latest issue

    LP = Latest Papers

    MI = Marketing Information

    OAA = Open Access Article

    RI = Recent issues

    TOC = Table of Contents

    rssFrequencyCode

    Translatable code denoting the frequency of the RSS feed

    		      

    Codes and their text equivalents:

    AS = As available

    B = Bi-monthly

    BW = Bi-weekly

    D = Daily

    I = Irregularly

    M = Monthly

    Q = Quarterly

    W = Weekly

    Y = Yearly

    rssSourceDescription

    Name of the source of the RSS feed (e.g., Publisher)

    		      

     

    rssUrl

    URL of the RSS feed

    		      

     
    corporateAuthors Corporate author(s) for the given titleId titleId     Returned in titleDetails reponse
    mflReviews Magazines for LibrariesTM Review(s) for the given titleId titleId     Returned in titleDetails response
    publicationHistory
    Publication history for the given titleId

    (example: 1961-1968; New Series 1971-1977; New Series 1991 (vol.1, no.51)

    		 titleId     Returned in titleDetails response
    relatedTitles Identifier, ISSN, name, type, and type code of the Related Title(s) for the given titleId titleId    

    Returned in titleDetails response

    Related Title Types:

    Alternative Media Edition

    Supplement

    Series

    Language Edition

    Translation

    Partial Translation

    International Edition

    Regional Edition

    Seasonal Edition

    Special Edition

    Abridged Edition

    Cumulative Edition

    Alternative Frequency Edition

    Issued With
    titleHistoryDetails Comments, country, sequence number, ISSN, and title of the Historic (former) Titles for a given titleId titleId     Returned in titleDetails response
    variantTitles Abbreviated, alternate, MEDLINE, and parallel language titles for a given titleId titleId     Returned in title Details response

    Dublin Core (DC) XML Output

    Field Name Explanation of Field Notes

    dc:title

    Title of the serial

     

    dc:publisher

    Commercial publisher of the serial

     

    dc:subject

    Ulrich s Subject classification(s)

     

    dc:language

    Language(s) in which the text of the serial is available

     

    dc:format

    Controlled vocabulary terms denoting the format editions in which the serial is available.

    Audio

    Braille

    CD-ROM

    Email

    LargeType

    LooseLeaf

    Microform

    Online

    Print

    Video

    dc:type

    Controlled vocabulary term(s) denoting the type of serial

    Abstract/Index

    Bulletin

    Catalog

    Database

    Directory

    Handbook/Manual

    Journal

    Magazine

    Monographic series

    Newsletter

    Newspaper

    Proceedings

    Report

    Yearbook

    dc:description

    Text describing what the serial is about

     

    Copyright 2018 Ex Libris, a ProQuest Company. All rights reserved.

    • Date Created: 9-Feb-2014

    • Last Edited Date: 02-Aug-2018

    • Old Article Number: 8943

    1. Back to top
    • Was this article helpful?

    Recommended articles

    1. Article type
      Topic
      Content Type
      Documentation
      Language
      English
      Product
      Ulrichs
    2. Tags
      1. Configuration