Web API

Introduction

The ISFDB currently provides 2 web APIs: getpub.cgi which is used to obtain publication metadata, and submission.cgi which is used to submit data to the ISFDB. There are currently no methods for obtaining author, title, series, or awards information from the ISFDB.

License Keys

Since registration is required to edit the ISFDB, the web API enforces that policy. Submitting data to the ISFDB requires a registered user ID, as well a license key which is your password for accessing the web API. If you are logged into the ISFDB, a license key can be generated by visiting http://www.isfdb.org/cgi-bin/edit/keygen.cgi and clicking on [Generate New Key]. For data submissions this key must appear within a LicenseKey XML tag following the Submitter tag.

getpub.cgi

The getpub.cgi application takes an ISBN for an argument, and returns an XML structure containing the metadata for that particular publication. If more than one publication is associated with that particular ISBN, multiple records will be generated. The Records tag indicates the number of records found, followed by some number of Publication records. A license key is not required to use this API. The URL for getpub.cgi should appear as follows:

 http://www.isfdb.org/cgi-bin/rest/getpub.cgi?0439176832

Example XML returned via call to getpub.cgi:

<?xml version="1.0" encoding="iso-8859-1" ?>
<ISFDB>
 <Records>2</Records>
 <Publications>
   <Publication>
     <Record>6260</Record>
     <Title>Castle</Title>
     <Authors>
       <Author>Garth Nix</Author>
     </Authors>
     <Year>2000-10-00</Year>
     <Isbn>0439176832</Isbn>
     <Publisher>Scholastic LucasBooks</Publisher>
     <Price>$4.99</Price>
     <Pages>215</Pages>
     <Binding>tp</Binding>
     <Type>NOVEL</Type>
     <CoverArtists>
       <Artist>Steve Rawlings</Artist>
     </CoverArtists>
   </Publication>
   <Publication>
     <Record>262384</Record>
     <Title>Castle</Title>
     <Authors>
       <Author>Garth Nix</Author>
     </Authors>
     <Year>2000-10-00</Year>
     <Isbn>0439176832</Isbn>
     <Publisher>Scholastic LucasBooks</Publisher>
     <Price>$5.99</Price>
     <Pages>215</Pages>
     <Binding>tp</Binding>
     <Type>NOVEL</Type>
     <CoverArtists>
       <Artist>Larry Rostant</Artist>
     </CoverArtists>
     <Note>13th printing. Locus Books Received, December 2007</Note>
   </Publication>
 </Publications>
</ISFDB>

Example python script utilizing getpub.cgi

Although getpub.cgi can be invoked via a browser, a more practical application is to invoke the URL via a programming interface, parsing the result with an XML parser, and then doing something of use with the resulting data. The following example shows the python code needed to obtain the XML data; it does not show an example of parsing the XML:

 import httplib
 
 def GetXml(isbn):
       webservice = httplib.HTTP(host)
       command = '/cgi-bin/rest/getpub.cgi?%s' % isbn
       webservice.putrequest("GET", command)
       webservice.putheader("Host", host)
       webservice.putheader("User-Agent", "Wget/1.9+cvs-stable (Red Hat modified)")
       webservice.endheaders()
       errcode, errmsg, headers = webservice.getreply()
       if errcode != 200:
               resp = webservice.getfile()
               print "Error:", errmsg
               print "Resp:", resp.read()
               resp.close()
               return 
       else:
               resp = webservice.getfile()
               raw = resp.read()
               resp.close()
               index = string.find(raw, '<?xml')
               return raw[index:]