Using the API

The xISSN API provides a set of methods for requesting information about a single ISSN value. The service can be used to

• list all relevant ISSNs and forms
• list all relevant ISSNs and all metadata
• list all relevant ISSNs, editions, as well as preceding/succeeding ISSNs
• get metadata about an ISSN
• re-calculate the ISSN checksum digit

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

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

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.

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.