Skip to main content
ExLibris
  • Subscribe by RSS
  • Ex Libris Knowledge Center

    Ulrichsweb: Using the Ulrichsweb API

    • Product: Ulrichs

    How do I use the Ulrichsweb API?

    You must have a current Ulrichsweb Terms of Use Non-Disclosure Agreement (NDA) on file with ProQuest. The 360 Services: XML APIs 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 1.0
    Documentation Updated: 16 July 2013

    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 ProQuest. 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>&sortIndex=<FIELD>&sortOrder=<ORDER>&start=<NUM>&rows=<NUM>
    The first section of <SEARCH_QUERY> is required:
    query=<FIELD>:<TERM>
    <FIELD> can be "title", "issn", or "publisher", 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", or "publisher", 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

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

    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

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

    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 fields are available for query: title, issn, publisher. 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

    Field Name
    Explanation of Field
    Notes
    Ulrichsweb Display
    id
    System identifier for the individual serial (Do not confuse with titleId)
     
    (No field level display)
    country
    Country of publication
     
    Search Results Column: Country
    Title Details: Country
    description
    Text describing what the serial is about
     
    Title Details: Description
    subject
    Ulrich s subject classification(s)
     
    Title Details: Subject
    formats
    Controlled vocabulary term(s) denoting the Format edition(s) in which the serial is available.
    Audio
    Braille
    CD-ROM
    Email
    LargeType
    LooseLeaf
    Microform
    Online
    Print
    Video
    Search Results Column: Format
    Search Results Facet: Format
    Title Details: Format
    status
    Controlled vocabulary term denoting the Publication Status of the serial
    Active
    Forthcoming
    Announced Never Published
    Ceased
    Merged/Incorporated
    Researched/Unresolved
    Suspended
    Search Results Column: Status
    Search Results Facet: Publication Status
    Title Details: Status
    title
    Title of the serial
     
    Search Results Column: Title
    Title Details: Title
    titleId
    Unique Ulrich s identifier for the title of the serial (Do not confuse with id)
    Numeric
    (No field level display)
    ISSN
    International Standard Serial Number of the format edition
    Format NNNN-NNNN
    Search Results Column: ISSN
    Title Details: ISSN
    publisher
    Name of commercial publisher of the serial
     
    Search Results Column: Publisher
    Title Details: Publisher
    startYear
    Year of first publication
     
    Search Results Column: Start Year
    Title Details: Start Year
    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
    Search Results Column: Frequency
    Title Details: Frequency
    languages
    Language(s) in which the text of the serial is available
    Text
    Search Results Column: Language of Text
    Title Details: Language of Text
    coden
    Alphanumeric code independently assigned by the Chemical Abstracts Service that uniquely identifies a serial, mainly for use on scientific and technical serials
     
    Title Details: CODEN
    otherFeatures
    Translatable codes representing additional feature(s) of the serial
    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
    Title Details: Other Features
    serialTypes
    Controlled vocabulary term(s) denoting the type(s) of serial
    Abstract/Index
    Bulletin
    Catalog
    Database
    Directory
    Handbook/Manual
    Journal
    Magazine
    Monographic series
    Newsletter
    Newspaper
    Proceedings
    Report
    Yearbook
    Search Results Facet: Serial Type
    Search Results Column: Serial Type
    Title Details: Serial Type
    deweyNumbers
    Dewey Decimal Number(s) for the serial
     
    Title Details: Dewey #
    lcnumber
    Library of Classification Number for the serial
     
    Title Details: LC #
    price
    Publisher-reported list price for the serial
    ISO Currency Code followed by institutional list price
    Text: See Full Record
    Text: Contact Publisher
    Search Results Column: Price
    toc
    Indication of whether the serial displays Tables of Contents in Ulrichsweb
    true
    false
    Search Results Column: Has TOC (icon)
    historicTitle
    Indication of whether the title is a former title of the serial (i.e., not the current title)
    true
    false
    Search Results Column: Historic Title (icon)
    refereed
    Indication of whether the serial is Refereed/peer-reviewed
    true
    false
    Search Results Colum: Refereed (icon)
    availableOnline
    Indication of whether the serial is available in an online format
    true
    false
    Search Results Column: Electronic (icon)
    openAccess
    Indication of whether the serial is available via Open Access
    true
    false
    Search Results Column: Open Access (icon)
    openAccessUrl
    If serial is Open Access, the Open Access URL for the serial
     
    Title Details: Open Access URL:
    reviewed
    Indication of whether the serial has a review in the Ulrich s record
    true
    false
    Search Results Column: Reviewed (icon)
    Title Details: Review
    contentTypes
    Controlled vocabulary term(s) denoting the primary target audience(s) of the serial
    Academic/Scholarly
    Bibliography
    Consumer
    Government
    Trade
    Search Results Column: Content Type
    Search Facet: Content Type
    Title Details: Content Type
    keyFeatures
    Translatable codes representing key features Ulrich s notes for the serial
    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)
    Search Results Facet: Key Features
    Title Details: Key Features
    rss
    Type, frequency, source, description and URL of RSS feed available for the serial
     
    Title Details: RSS Availability
    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
    Title Details: RSS Availability: Type
    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
    Title Details: RSS Availability: Frequency
    rssSourceDescription
    Name of the source of the RSS feed (e.g., Publisher)
     
    Title Details: RSS Availability: Source
    rssUrl
    URL of the RSS feed
     
    Title Details: RSS Availability: URL

    Dublin Core (DC) XML Output

    Field Name
    Explanation of Field
    Notes
    Ulrichsweb Display
    dc:title
    Title of the serial
     
    Search Results Column: Title
    Title Details: Title
    dc:publisher
    Commercial publisher of the serial
     
    Search Results Column: Publisher
    Title Details: Publisher
    dc:subject
    Ulrich s Subject classification(s)
     
    Title Details: Subject
    dc:language
    Language(s) in which the text of the serial is available
     
    Search Results Column: Language of Text
    Title Details: Language of Text
    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
    Search Results Column: Format
    Search Results Facet: Format
    Title Details: Format
    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
    Search Results Facet: Serial Type
    Search Results Column: Serial Type
    Title Details: Serial Type
    dc:description
    Text describing what the serial is about
       

    Copyright 2016 ProQuest. All rights reserved.

    • Date Created: 9-Feb-2014
    • Last Edited Date: 20-Dec-2016
    • Old Article Number: 8943
    • Was this article helpful?