WorldCat
Advanced Search
My Account Logout Get E-mail Updates
WorldCat » WorldCat Affiliate tools » xISSN (Web service) » API

xISSN (Web service)

Use this Web service to retrieve a list of International Standard Serial Numbers (ISSNs) associated with a submitted ISSN, based on WorldCat information.

xISSN API

Overview

The xISSN API provides a set of methods for requesting information about a single ISSN value. All request formats have a list of required parameters. The required parameter method is used to specify the calling method. The required parameter format is used to specify a response format, such as XML, XHTML, JSON, Python or Ruby formats. The optional parameter fl controls what fields to return. The required parameter ai specifies the WorldCat Affiliate ID. The response is always a list of ISSN numbers with selected metadata fields. The xISSN service base URL is:

      http://xissn.worldcat.org/webservices/xid/issn/
    

For example, the following query requests the title history of 0036-8075 [Science]:

http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getHistory&format=xml&ai=[affiliate id]&fl=form

The response is the XML formatted message shown below:

    	<?xml version="1.0" encoding="UTF-8"?> 
	<rsp xmlns="http://worldcat.org/xid/issn/" stat="ok">
	  <group  rel="this" >
	    <issn  form="JD">1095-9203</issn>
	    <issn  form="JB" >0036-8075</issn>
	  </group>
	  <group rel="preceding" marccode="780" subrel="5">
	    <issn form="JB">0096-3771</issn>
	  </group>
	</rsp>
  

Groups and Relationships

ISSNs are organized in same group if they are different editions of same serial (online, paper, CD-ROM, etc.); groups are associated by historical relationships, as defined in the MARC 780 and 785 fields.

In above example, ISSN 1095-9203 is the online form of ISSN 0036-8075, so they are in same group. They both have a preceding ISSN with the value 0096-3771.

Worldcat Affiliate ID

You are recommended to register a Worldcat Affiliate ID before using the service. An affiliate ID can be used to track usage of your application. To provide an affiliate ID in a request, simply add "&ai=[affiliate id]", such as:

http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=xml&ai=[affiliate id]

Affiliate ID based usage tracking is a free service. You can check your affiliate ID based usage from the xID admin page.

List of all parameters

  • method: mandatory - possible values include: fixChecksum, getMetadata, getEditions, getHistory
  • format: mandatory - possible values include: xml, html, json, python, ruby
  • fl:optional, "fl" parameter controls what stored fields are returned, e.g. fl=* return all fields, fl=form,title returns form and title fields.
  • ai: mandatory

Request types

getForms

This service returns a list of ISSNs and its production form information in same group as the requested ISSN.

 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getForms&format=xml

The response is an XML formatted message similar to this example.

    	<?xml version="1.0" encoding="UTF-8"?> 
	<rsp xmlns="http://worldcat.org/xid/issn/" stat="ok">
	  <group  rel="this" >
	    <issn  form="JD">1095-9203</issn>
	    <issn  form="JB" >0036-8075</issn>
	  </group>
	</rsp>
  

getEditions

This service returns a list of ISSNs in same group as the requested ISSN.

 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=xml&ai=[affiliate id]

The response is an XML formatted message similar to this example.

    	<?xml version="1.0" encoding="UTF-8"?> 
	<rsp xmlns="http://worldcat.org/xid/issn/" stat="ok">
	  <group  rel="this" >
	    <issn  form="JD">1095-9203</issn>
	    <issn  form="JB" >0036-8075</issn>
	  </group>
	</rsp>
  

getHistory

This service returns a list of ISSNs in same group as the requested ISSN, as well as preceding/succeeding groups.

 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getHistory&format=xml&ai=[affiliate id]&fl=form

The response is an XML formatted message similar to this example.

    	<?xml version="1.0" encoding="UTF-8"?> 
	<rsp xmlns="http://worldcat.org/xid/issn/" stat="ok">
	  <group  rel="this" >
	    <issn  form="JD">1095-9203</issn>
	    <issn  form="JB" >0036-8075</issn>
	  </group>
	  <group rel="preceding" marccode="780" subrel="5">
	    <issn form="JB">0096-3771</issn>
	  </group>
	</rsp>
  

getMetadata

This service returns metadata about the requested ISSN.

 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getMetadata&format=xml&fl=form&ai=[affiliate id]

The response is an XML formatted message similar to this example.

    	<?xml version="1.0" encoding="UTF-8"?> 
	<rsp xmlns="http://worldcat.org/xid/issn/" stat="ok">
	  <group  rel="this" >
	    <issn  form="JB" >0036-8075</issn>
	  </group>
	</rsp>

  

fixChecksum

This service re-calculates the checksum digit of an ISSN number.

 http://xissn.worldcat.org/webservices/xid/issn/0036-8074?method=fixChecksum&format=xml&ai=[affiliate id]

The response is an XML formatted message similar to this example.

	<rsp xmlns="http://worldcat.org/xid/issn/" stat="ok">
	  <group  rel="this" >
	  	  <issn>0036-8075</issn>
	  </group>
	</rsp>
  

Responses in detail

Valid conditions and metadata fields

If the request is valid, xISSN service returns a list of matched ISSNs and requested metadata fields, with a "stat=ok" indication. For example:

	<?xml version="1.0" encoding="UTF-8"?> 
	<rsp xmlns="http://worldcat.org/xid/issn/" stat="ok">
	  <group  rel="this" >
	    <issn  form="JD">1095-9203</issn>
	    <issn  form="JB" >0036-8075</issn>
	  </group>
	  <group rel="preceding" marccode="780" subrel="5">
	    <issn form="JB">0096-3771</issn>
	  </group>
	</rsp>
  

Metadata fields for an ISSN

A number of metadata fields can be associated with an ISSN number:

  • form: Each ISSN has a production form, indicated by an ONIX production form code. Current supported values include: JB ( Printed serial ), JC ( Serial distributed electronically by carrier ) ,JD ( Electronic serial distributed online ), MA ( Microform )
  • oclcnum: Oclcnum
  • peerreview: Peerreview, 'Y' if the ISSN is peer-reviewed, 'N' if the ISSN is not peer-reviewed.
  • publisher: Publisher
  • rawcoverage: Human-readable Coverage
  • title: Title
  • issnl: Linking ISSN, as defined here
  • rssurl: Journal feed URL, data obtained from ticTOCS

Metadata fields for a group

A number of metadata fields can be associated with a group:

  1. rel: relationship between the group and requested ISSN. Current supported values include:
    • this: the group which contains requested ISSN.
    • preceding: containing the immediate predecessor of the requested ISSN - see the MARC 780 field specification
    • succeeding: containing the immediate successor of the requested ISSN - see MARC 785 field specification
  2. marccode: MARC code of the historical relationship. This field can have the values "780" (preceding) or "785" (suceeding).
  3. subrel: Type of relationship: corresponds to the "Type of relationship" indicator in the MARC 780 and 785 field specifications.

Invalid and exception conditions

If the request is invalid or the usage limit has been reached, the response will return header only, with appropriate status code. For example, a request to
 http://xissn.worldcat.org/webservices/xid/issn/123456789?ai=[affiliate id]
returns following response:

	<?xml version="1.0" encoding="UTF-8" ?>
	<rsp xmlns="http://worldcat.org/xid/issn/" stat="invalidId"/>
      

XML schema for response XML

The XML schema in xissn.xsd validates the xISSN response XML format.

CSV, TEXT, JSON, Python, Ruby, PHP, and XHTML response

Several other serialization formats are supported, Below is an example of each:

 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=html&ai=[affiliate id]
 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=json&ai=[affiliate id]
 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=python&ai=[affiliate id]
 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=ruby&ai=[affiliate id]
 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=php&ai=[affiliate id]
 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=csv (comma-delimited file)
 http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=txt (tab-delimited file) 

Subscription-specific usage

Access token (available for subscription user)

Commercial and heavy usage users could obtain an access token. To provide a token in request, add "&token=[token]&hash=[hashvalue]". The hash value is calculated per request, such as:

http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=xml&token=[token]&hash=[hash]

The hash is calculated this way:

      md5(requestURL+"|"+requestIPaddress+"|"+secret)
    
e.g. If you request ip address is "128.12.12.1", your token is "mytoken", and your secret is "mysecret", and you are requesting http://xissn.worldcat.org/webservices/xid/issn/0036-8075?method=getEditions&format=xml, the md5 hash will be calculate like:
  md5("http://xissn.worldcat.org/webservices/xid/issn/0036-8075|128.12.12.1|mysecret")
=32a1ece026ab738691eab1ceb76656ba
And you complete request will be
  http://xissn.worldcat.org/webservices/xid/issn/0036-8075?
  method=getEditions&format=xml&token=mytoken&hash=32a1ece026ab738691eab1ceb76656ba
At server end we will re-run the hash algorithm and compare hash value. You can maintain access token from xISSN account page.

IP address-controlled access (available for subscription user)

Commercial and heavy usage users could also use IP address-controlled access. IP address-controlled access does not require any parameter in xISSN request, you can maintain IP address-controlled access from xid account page. It's mandatory to put affiliate ID in request if you choose to use IP address-controlled access.