Using the API

The API is comprised of five request types:

• getEditions returns all editions and forms related to the requested ISBN as well as their basic metadata
• getMetadata returns basic metadata about the requested ISBN
• to13 converts the requested ISBN to 13 digits
• to10 converts the requested ISBN to 10 digits
• fixChecksum re-calculate the checksum digit of the request ISBN number

Responses from the API can be returned in eight different format:

• XML
• CSV
• TEXT
• JSON
• Python
• Ruby
• PHP
• XHTML response

In addition to the basic request protocol the services also can be access via the following alternative request formats:

• OpenURL support
• unAPI support
• Short URL

How xISBN works

ISBNs are related to each other in WorldCat using an algorithm developed by OCLC Research. The algorithm restructures WorldCat bibliographic records to conform to the FRBR conceptual model for information objects. For instance, rather than requiring an end user to traverse multiple records that represent many different manifestations of a book—including printings, hardback or paperback editions or even filmed versions—"FRBRized" WorldCat information allows that user to review a core record that lists all manifestations.

The xISBN Web service queries database tables in WorldCat created by the FRBR algorithm.

Worldcat Affiliate ID

You are encouraged to obtain 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 request, simply add "&ai=[affiliate ID]", such as:

http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&format=xml&ai=[affiliate ID]

Affiliate ID based usage track is a free service. You can check affiliate ID based usage from xISBN admin page.

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://xisbn.worldcat.org/webservices/xid/isbn/0596002815?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://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&format=xml, the md5 hash will be calculate like:

md5("http://xisbn.worldcat.org/webservices/xid/isbn/0596002815|128.12.12.1|mysecret")
=da82217b05017710f998f6ebe8b07ce6

And you complete request will be

http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?
  method=getEditions&format=xml&token=mytoken&hash=da82217b05017710f998f6ebe8b07ce6

At server end we will re-run the hash algorithm and compare hash value. You can maintain access token from xISBN 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 xISBN 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.