View source

From ISFDB

You do not have permission to do that, for the following reasons:
You do not have permission to edit pages in the Page namespace.
The action you have requested is limited to users in one of the groups user, Write.
You can view and copy the source of this page:
==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==

Submitting data to the ISFDB via the Web API requires a valid user ID and a license key. When logged into the ISFDB with your user ID, 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. In addition, the submitting user's ID must be added to the whitelist of authorized submitters maintained by the ISFDB administrators. Post on the ISFDB Moderator Noticeboard to request access.

Retrieving data from the ISFDB using the Web API doesn't require a license key.

== Publication Lookups ==

At this time there are two ways to retrieve publication data from the ISFDB database: by ISBN (getpub.cgi) and by External ID (getpub_by_ID.cgi). The XML data returned by these two APIs is identical. A license key is not required to use them. A valid query returns an XML payload which includes the following:
* the '''Records''' tag which indicates the number of records found
* zero or more '''Publication''' records containing the metadata for matching ISFDB publication record(s)

Example:

<source lang="xml">
<?xml version="1.0" encoding="iso-8859-1" ?>
<ISFDB>
 <Records>1</Records>
 <Publications>
   <Publication>
     <Record>325837</Record>
     <Title>The Winchester Horror</Title>
     <Authors>
       <Author>William F. Nolan</Author>
     </Authors>
     <Year>1998-00-00</Year>
     <Isbn>1881475530</Isbn>
     <Publisher>Cemetery Dance Publications</Publisher>
     <PubSeries>Cemetery Dance Novella</PubSeries>
     <PubSeriesNum>6</PubSeriesNum>
     <Price>$30.00</Price>
     <Pages>111</Pages>
     <Binding>hc</Binding>
     <Type>CHAPBOOK</Type>
     <Tag>THWNCHSTRH1998</Tag>
     <CoverArtists>
       <Artist>Eric Powell</Artist>
     </CoverArtists>
     <Note>Hardcover Limited Edition of 450 signed and numbered copies bound in full-cloth and Smyth sewn</Note>
     <External_IDs>
       <External_ID>
          <IDtype>1</IDtype>
          <IDtypeName>ASIN</IDtypeName>
          <IDvalue>B01G1K1RV8</IDvalue>
       </External_ID>
     </External_IDs>
   </Publication>
 </Publications>
</ISFDB>
</source>

=== getpub.cgi ===

The getpub.cgi API takes an ISBN as its argument. If more than one publication is associated with the requested ISBN, multiple publication records will be returned. If an ISBN-10 is submitted, the API will retrieve and return the data for the requested ISBN as well as for the equivalent ISBN-13 (and vice versa.) The URL for getpub.cgi should appear as follows: http://www.isfdb.org/cgi-bin/rest/getpub.cgi?0439176832

=== getpub_by_ID.cgi ===

The getpub_by_ID.cgi API takes two arguments. The first argument is the External ID type -- see [http://www.isfdb.org/cgi-bin/search.cgi Advanced Publication Search by External Identifier] for a list of currently supported External ID types. The second argument is the External ID value.

If more than one publication is associated with the requested External ID, multiple publication records will be returned.  The URL for getpub_by_ID.cgi should appear as follows: http://www.isfdb.org/cgi-bin/rest/getpub_by_ID.cgi?ASIN+B0764JW7DK

===Example python script utilizing getpub.cgi===

Although getpub.cgi and getpub_by_ID.cgi can be invoked via a browser, a more practical application is to invoke a URL via a programming interface, parse the result with an XML parser, and then do something 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 payload: 
<source lang="python">
import httplib

host = "www.isfdb.org"

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 = raw.find('<?xml')
              return raw[index:]
</source>

===Error Conditions===

If no matching publication records are found, getpub.cgi and getpub_by_ID.cgi will return an XML structure with the number of records set to zero:
<source lang="xml">
<?xml version="1.0" encoding="iso-8859-1" ?>
<ISFDB>
  <Records>0</Records>
  <Publications>
  </Publications>
</ISFDB>
</source>

If the submitted query contains invalid parameters, the invoked Web API will return a short error message explaining the use of the API.

==submission.cgi==

The submission.cgi application allows a remote user to create ISFDB submissions programmatically. Note that the use of submission.cgi requires a valid License Key. See [[Web_API#License_Keys]] for instructions on obtaining a License Key.

Any of the data payloads defined in the [[Data Submission Formats]] article are accepted. The format of the XML data is identical to that used for local submissions, with the exception that the user's license key must be inserted after the '''Submitter''' tag. The user's registered login name should be contained within the '''Submitter''' tag, and the user's current license key should be contained with the '''LicenseKey''' tag. The URL for submission.cgi should appear as follows:

http://www.isfdb.org/cgi-bin/rest/submission.cgi

Submissions are placed in the moderator queue as with an ISFDB edit, and are not integrated into the database until a moderator approves it. As such it is important that you not flood the moderator queue with hundreds of submissions. In general you should only post no more than 20 submissions per session, until they are processed out by a moderator. If you want a submission to be automatically put on hold on behalf of a particular moderator, add <nowiki><Holder>moderator_user_name</Holder> after <IsfdbSubmission></nowiki>.

An example submission XML payload follows, with the LicenseKey x'd out:
<source lang="xml">
<?xml version="1.0" encoding="iso-8859-1" ?>
<IsfdbSubmission>
 <Holder>Ahasuerus</Holder>
 <NewPub>
   <Submitter>Dissembler</Submitter>
   <LicenseKey>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</LicenseKey>
   <Subject>Lady of the Glen: A Novel of 17th-Century Scotland and the Massacre of Glencoe</Subject>
   <Isbn>1575661292</Isbn>
   <Title>Lady of the Glen: A Novel of 17th-Century Scotland and the Massacre of Glencoe</Title>
   <Year>1997-01-01</Year>
   <Price>$14.95</Price>
   <Language>English</Language>
   <Publisher>Kensington</Publisher>
   <PubSeries>Time Romances</PubSeries>
   <PubSeriesNum>17</PubSeriesNum>
   <Pages>432</Pages>
   <Authors>
     <Author>Jennifer Roberson</Author>
   </Authors>
   <Binding>tp</Binding>
   <PubType>NOVEL</PubType>
   <Image>http://ecx.images-amazon.com/images/I/519xedh9nrL.jpg</Image>
   <Note>Data from Amazon.com as of 2008-05-08</Note>
 </NewPub>
<IsfdbSubmission>
</source>

===Example python script utilizing submission.cgi===
The submission.cgi application uses the http POST method, so it can not be invoked via a web browser. Once a proper XML payload has been constructed as described above, a connection needs to be made to the ISFDB web server, and the appropriate http header needs to be sent, including content type and length information. This example below shows how this can be implemented in python:
<source lang="python">
import httplib

host = "www.isfdb.org"

def SendXml(xmlmsg):
      webservice = httplib.HTTP(host)
      webservice.putrequest("POST", "/cgi-bin/rest/submission.cgi")
      webservice.putheader("Host", host)
      webservice.putheader("Content-type", "text/xml; charset=\"iso-8859-1\"")
      webservice.putheader("Content-length", "%d" % len(xmlmsg))
      webservice.endheaders()
      webservice.send(xmlmsg)

      errcode, errmsg, headers = webservice.getreply()
      if errcode != 200:
              resp = webservice.getfile()
              print "Error:", errmsg
      else:
              resp = webservice.getfile()
      resp.close()
</source>

===Error Conditions===
In the event of an error condition, submission.cgi will return an XML structure with a Status of FAIL (success will return OK). The cause of the error can be found within the Error tag:
<source lang="xml">
<?xml version="1.0" encoding="iso-8859-1" ?>
<ISFDB>
  <Status>FAIL</Status>
  <Error>Bad XML data</Error>
</ISFDB>
</source>
Return to Web API.
Retrieved from "http://www.isfdb.org/wiki/index.php/Web_API"
View source

From ISFDB

Views

Personal tools

Navigation

Search

Toolbox
