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

xISBN (Web service)

Use this Web service to map book-related identifiers (ISBN, LCCN, OCLC number), based on WorldCat information. Free and subscription versions are available.

xISBN API

  1. Overview
  2. Request
  3. Response in details
  4. Alternative request format
  5. Subscription-specific usage

Overview

The xISBN API provides a set of methods corresponding to a single, known ISBN value. All request formats take a list of named 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 optional parameter library limits search scope to a library or collection. The response is always a list of normalized ISBN numbers, with requested metadata fields. The xISBN service endpoint URL is:

      http://xisbn.worldcat.org/webservices/xid/isbn/

For example, to request all editions of 0596002815 [Learning Python], request is:

http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&format=xml&fl=form,year,lang,ed

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

    	<?xml version="1.0" encoding="UTF-8"?>
    	<rsp xmlns="http://worldcat.org/xid/isbn/" stat="ok">
    	    <isbn form="BA" year="2004" lang="eng" ed="2nd ed.">0596002815</isbn>
    	    <isbn form="BA DA" year="1999" lang="eng">1565928938</isbn>
    	    <isbn form="BA" year="1999" lang="eng" ed="1st ed.">1565924649</isbn>
    	</rsp>
and to request a thirteen digits ISBN number of 0596002815, 
http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=to13&format=xml
The response is: 
	<rsp xmlns="http://worldcat.org/xid/isbn/" stat="ok">
	  <isbn>9780596002817</isbn>
	</rsp>

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 and does not associate access privilege. You can check affiliate ID based usage from xISBN admin page.

Search in a library

 This feature limits search scope to a particular library's holding, we also treat any collections as a library in general. Current support value includes: We also support limiting search scope to a particular library's holding, e.g. "library=IMD" limits search scope to Indianapolis-Marion County Library. If you are interested in adding your library, please contact us for details.

Result Paging

xISBN by default returns first 1000 matched ISBNs, however there are a few works with more than 1000 matches (e.g. Bible), in that case, the remaining ISBNs can be fetched by the paging method. We use "startIndex" and "count" parameters to page the result. The same technique can be used if the client desired less than 1000 records in response. The definition of startIndex and count is same as OpenSearch Specification. To do a paging request: 

	http://xisbn.worldcat.org/webservices/xid/isbn/9789574760442?method=getEditions&startIndex=1&count=2

List of all parameters
  • method: mandatory, possible values include: to10,to13, fixChecksum, getMetadata, getEditions
  • format: mandatory, possible values include: xml, html,json,python,ruby,text,csv
  • library: optional, limits the search to a library, possible values include: ebook,bookmooch,wikipedia,paperbackswap,oca, freeebook,etc.
  • fl:optional, "fl" parameter controls what stored fields are returned, e.g. fl=* return all fields, fl=ed,lang returns edition and language fields.
  • startIndex:optional, the index of the first search result desired by the client.
  • count:optioanl, the number of search results desired by the client.
  • callback:optional, JSON callback functions, only valid for JSON format
  • ai: optional
  • token:optional (subscription user-only)
  • hash:optional (subscription user-only)

Request

getEditions

This service returns a list of relevant ISBNs and requested metadata fields. 

 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&format=xml&fl=form,year,lang,ed

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

     	<?xml version="1.0" encoding="UTF-8"?>
    	<rsp xmlns="http://worldcat.org/xid/isbn/" stat="ok">
    	    <isbn form="BA" year="2004" lang="eng" ed="2nd ed.">0596002815</isbn>
    	    <isbn form="BA DA" year="1999" lang="eng">1565928938</isbn>
    	    <isbn form="BA" year="1999" lang="eng" ed="1st ed.">1565924649</isbn>
    	</rsp>

By default, this method returns a list of relevant ISBNs

 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&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/isbn/" stat="ok">
    	    <isbn>0596002815</isbn>
    	    <isbn>1565928938</isbn>
    	    <isbn>1565924649</isbn>
    	</rsp>

getMetadata

This service returns metadata information about requested ISBN. 

 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getMetadata&format=xml&fl=*

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

	<?xml version="1.0" encoding="UTF-8"?>
    	<rsp xmlns="http://worldcat.org/xid/isbn/" stat="ok">
    	    <isbn title="Learning Python" form="BA" year="2004" lang="eng" ed="2nd ed.">0596002815</isbn>
    	</rsp>

to13

This service converts an ISBN number to a normalized 13 digits ISBN format. 

 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=to13&format=xml

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

	<rsp xmlns="http://worldcat.org/xid/isbn/" stat="ok">
	  <isbn>9780596002817</isbn>
	</rsp>

to10

This service converts an ISBN number to a normalized 10 digits ISBN format. 

 http://xisbn.worldcat.org/webservices/xid/isbn/978-0-596-00281-7?method=to10&format=xml

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

	<rsp xmlns="http://worldcat.org/xid/isbn/" stat="ok">
	  <isbn>0596002815</isbn>
	</rsp>

fixChecksum

This service re-calculate the checksum digit of an ISBN number. 

 http://xisbn.worldcat.org/webservices/xid/isbn/978-0-596-00281-6?method=fixChecksum&format=xml

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

	<rsp xmlns="http://worldcat.org/xid/isbn/" stat="ok">
	  <isbn>9780596002817</isbn>
	</rsp>

Response in details

Valid conditions and metadata fields

 If the request is valid, xISBN service returns a list of matched ISBNs and requested metadata fields, with a "stat=ok" indication, such as: 

	<?xml version="1.0" encoding="UTF-8"?>
    	<rsp xmlns="http://worldcat.org/xid/isbn/" stat="ok">
    	    <isbn title="Learning Python" form="BA" year="2004" lang="eng" ed="2nd ed." author="Lutz, Mark." publisher="O'Reilly">0596002815</isbn>
    	</rsp>

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

  • author: Author
  • city: City of Publication
  • ed: Edition
  • form: The ONIX production form code, this field is space-delimited if multiple values exist. Current supported values include:

    AA (Audio), BA (Book), BB (Hardcover), BC (Paperback), DA (Digital),FA (Film or transparency), MA(Microform), VA(Video).

  • lang: The language field uses three-character MARC Code List for Languages.
  • lccn: Library Of Congress Control Number, this field is space-delimited if multiple values exist.
  • oclcnum: OCLC number, this field is space-delimited if multiple values exist.
  • originalLang: Original Language
  • publisher: Publisher
  • title: Title
  • url: URL link to electronic resource, this field is space-delimited if multiple values exist.
  • year: Publication year

The request decides which metadata field to return:

  • In responding to to10,to13, and fixChecksum method, only ISBN number is returned.
  • In responding to getEditions and getMetadata method, the "fl" parameter is used to control what fields are returned, such as fl=lccn,oclcnmu, fl=*returns all fields.

Default method and format

 The default method is getEditions and default format is xml, for example: 
http://xisbn.worldcat.org/webservices/xid/isbn/0596002815

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

    	<?xml version="1.0" encoding="UTF-8"?>
    	<rsp xmlns="http://worldcat.org/xid/isbn/" stat="ok">
    	    <isbn>0596002815</isbn>
    	    <isbn>1565928938</isbn>
    	    <isbn>1565924649</isbn>
    	</rsp>

Invalid and exception conditions

If the request is invalid or the usage has reached limits, the response will return header only, with appropriate status code. For example, a request to 
 http://xisbn.worldcat.org/webservices/xid/isbn/12345678901234
returns following response:

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

Status code

Possible status code includes:
  • ok: correct request and response
  • unknownField: the request field is not supported
  • unknownFormat: the request format is not supported
  • unknownId: the request identifier looks like a valid ISBN number and unknown to xISBN service
  • unknownLibrary: the request library is not supported
  • unknownMethod: the request method is not supported
  • invalidId: the request identifier is not a valid ISBN number
  • overlimit: the request is throttled, only header is returned
  • invalidAffiliateId: invalid affiliate id
  • invalidHash: invalid hash (subscription only)
  • invalidToken: invalid access token (subscription only)

Sorting of result set

 The result is ordered in following way:
  1. ISBN passed into the service is always returned as the first ISBN
  2. Following the initial ISBN, values are returned ranked by holdings in WorldCat (i.e. number of libraries signifying ownership of item against respective bibliographic records) - order is descending (most held to least held)

JSON callback

 The callback parameter (callback=function) wraps the JSON output text in parentheses and a function name of your choosing. For example: 
	  http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getMetadata&format=json&fl=*&callback=mymethod
Results wrapped in callbacks look like this: 
	  mymethod({
	  "stat":"ok",
	  "list":[{
	  "publisher":"O'Reilly",
	  "form":["BA"],
	  "lang":"eng",
	  "city":"Beijing",
	  "author":"by Mark Lutz and David Ascher.",
	  "ed":"2nd ed.",
	  "year":"2004",
	  "isbn":["0596002815"],
	  "title":"Learning Python",
	  "oclcnum":[
	  "51964644",
	  "54619668"]}]})
JSON output is native JavaScript, and callbacks are particularly useful for use with web service requests in client-side JavaScript. Yahoo's JSON page has more details about how JSON callback works.

XML schema for response XML

 The XML schema in xisbn.xsd validates xISBN response XML format.

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

Several other serialization formats are supported, You may check a sample such as: 

 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&fl=*&format=html
 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&format=json
 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&fl=*&format=python
 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&fl=*&format=ruby
 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&fl=*&format=php
 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&fl=*&format=csv (comma-delimited file)
 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&fl=*&format=txt (tab-delimited file)

Alternate request format

OpenURL

The OpenURL Framework defines an architecture for creating context-sensitive services. The OpenURL Endpoint URL is:

 http://xisbn.worldcat.org/webservices/xid/openurl/
In OpenURL request, the rft_id is a complete ISBN URI, such as URN:ISBN:0596002815; and svc_id is "http://worldcat.org/xid/isbn/"+method+"_"+format. For example (Note: svc_id intentionally not URL-encoded for readability) : 


http://xisbn.worldcat.org/webservices/xid/openurl?rft_id=URN:ISBN:0596002815&url_ver=Z39.88-2004&svc_id=http://worldcat.org/xid/isbn/to13_xml

unAPI

unAPI is a tiny HTTP API for the few basic operations necessary to copy discrete, identified content from any kind of web application. The unAPI Endpoint URL is :

 http://xisbn.worldcat.org/webservices/xid/unapi/

In unAPI request, the id is a complete ISBN URI, such as URN:ISBN:0596002815; and format argument is method+"_"+format. For example:

To get an XML response for ISBN number 0596002815:

http://xisbn.worldcat.org/webservices/xid/unapi?id=URN:ISBN:0596002815&format=getEditions_xml

To get a JSON response for ISBN number 0596002815:

http://xisbn.worldcat.org/webservices/xid/unapi?id=URN:ISBN:0596002815&format=getEditions_json

short URL

 It's also possible to request xISBN service by more REST-ful style in a few cases:

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