WorldCat
Advanced Search
 
Get E-mail Updates Feedback
WorldCat » WorldCat Affiliate tools » WorldCat Web service: xISBN » API

Web service: xISBN

Use this Web service to retrieve a list of International Standard Book Numbers (ISBNs) associated with a submitted ISBN, based on WorldCat information.
This is a beta service and subject to change without prior notice, for comments please visit http://listserv.oclc.org/scripts/wa.exe?A0=XIDENTIFIER-L.
  1. Overview
  2. Request
  3. Response in details
  4. OpenURL support
  5. unAPI support
  6. Cool URI convention

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 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 will help us provide better service. 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]

Access token

Commercial and heavy usage users should contact us and 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]

List of all parameters
  • method: mandatory, possible values include: to10,to13, fixChecksum, getMetadata, getEditions
  • 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=ed,lang returns edition and language fields.
  • ai: optional
  • token:optional
  • hash:optional

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.">0596002815</isbn>
    	</rsp>

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

  • title: Title of the requested ISBN
  • year: Publication year
  • ed: Edition
  • lang: The language field uses three-character MARC Code List for Languages.
  • 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).

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. Current supported fields include: year,ed,lang,title,and form; 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="unknownId"/>

Status code

Possible status code includes:
  • ok: correct request and response
  • unknownId: the request identifier is not a valid ISBN number
  • unknownMethod: the request method is not supported
  • unknownFormat: the request format is not supported
  • unknownField: the request field is not supported
  • overlimit: the request is throttled, only header is returned

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)

XML schema for response XML

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

JSON, Python, Ruby, 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&format=html
 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&format=json
 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&format=python
 http://xisbn.worldcat.org/webservices/xid/isbn/0596002815?method=getEditions&format=ruby

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

Cool URI convention

 xISBN supports cool URI convention, it's

Other information for this service: