This document describes the XML interface to Credo Reference.
Credo Reference is a customizable general reference solution for learners and librarians. Its full-text, aggregated content covers every major subject from the world's best publishers of reference. Access is limited to subscribers who have login credentials. Variations in products and subscriptions means that a given subscriber may have access to an individual book or to hundreds of books.
The electronic data is organized as a series of titles (e.g., The Columbia Encyclopedia is one such title), each of which is divided into a number of entries (the definition of gravity for example). Each entry is composed of a heading (gravity) and a body (definition of gravity). Each entry also has a unique identifier. Entries are also often linked to other Related Entries within the Credo Reference collection. Titles are grouped into broad categories called shelves which permit searching or browsing to be limited to the titles in the requested category.
Data is in the XML interface served in one of five XML structures:
An entry object is straightforward - it's a structure composed of a heading and a body for a specified entry. A results object contains the results of a specified search. A related entry object describes what links exist from a specified entry to other entries - these entries can be in the same or a different title. Only links to titles accessible by a client account are listed. Also defined in this document is the ability to access a list of the book categories a client has access to.
The following sections describe the syntax for requesting XML objects, the format of each XML object along with appropriate examples.
Prior versions of this interface, using urls ending in .jsp, are now deprecated. The mapping between deprecated and current URLs is in Deprecated URLs.
The XML interface can use either IP or username/password authentication. If IP authentication is enabled for your account, Credo data can be accessed with no explicit authentication steps.
For username/password authentication, the initial request to the XML interface must log the user into their associated client account. The request provides the client username and password. The returned XML document will contain an authentication token that is used on all subsequent requests from the same client. The authentication token has a life-span of 24 hours.
http://xml.credoreference.com/xmltokenget.do?client=clientname&password=password
If the username and password are valid, the response of the xmltokenget.do request will have a single element in the return:
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE epage
PUBLIC '-//xrefer//DTD XML Interface 2//EN' '/rpage_2.dtd'>
<?xml version="1.0" encoding="iso-8859-1"?>
<token>696/1139325031375/046c91fb527d2d35ad6c466d4c24d21a</token>
The text of this token (minus the enclosing element) should be
inserted into the membertoken parameter of each subsequent
request. If the username and password are not recognized, an HTTP
response code 403 - Forbidden will be returned with an empty token.
If the client or password are not provided a 400 - Bad Request will be returned
with an empty token. If the token is expired or is not provided on other requests made through
the XML interface an HTTP response code 401 - Unauthorized will be
returned.
The URL to perform a search is as follows:
http://xml.credoreference.com/xmlsearch.do?client=clientname&membertoken=token&searchterm=phrase&shelf=&resfrom=1&resto=10&maxchars=100
where
The result object returned by the search is described inResults Object.
The URL to perform a search is as follows:
http://xml.credoreference.com/xmlsearchtitles.do?client=clientname&membertoken=token&searchterm=phrase&resfrom=1&resto=10&maxchars=100&volumes=vol-id-list
Where
The result object returned by the search is described in Results Object.
Each result in the result object has an entry identifier in the <eid> tag. To retrieve the XML object for the entry place the entry id in the id parameter as shown here:
http://xml.credoreference.com/xmlentry.do?client=clientname&membertoken=token&baseurl=http://www.credoreference.com/entry.do?&id=123456
Where
The entry XML returned by the request is described in Entry Object.
If you are doing meta-searching and would like to perform the search in XML, but want to then link the results to the Credo Reference HTML interface, you can extract the <eid> from any XML result set, and paste it into a URL of the following syntax:
http://www.credoreference.com/entry.do?id=entry identifier
Related Entries are "see also" entries related to a retrieved entry; many are entries from other books. You can obtain pageable list of Related Entries by using the following URL:
http://xml.credoreference.com/xmlrelateds.do?client=clientname&membertoken=token&id=209845&shelf=&xreffrom=1&xrefto=10&maxchars=100
Where
The related entries object returned by the request is described in Related Entries Object.
Each of the books in Credo Reference are organized into a number of broad categories (called shelves) listed here:
| Category | Used as a shelf= parameter |
|---|---|
| Art | shelf=art |
| Bilinguals | shelf=genref.bilingual |
| Biography | shelf=genref.bio |
| Business | shelf=business |
| Dictionaries | shelf=genref.dict |
| Encyclopedias | shelf=genref.ency |
| Food | shelf=food |
| Geography | shelf=geography |
| History | shelf=history |
| Language | shelf=language |
| Law | shelf=law |
| Literature | shelf=literature |
| Medicine | shelf=medicine |
| Music | shelf=music |
| Philosophy | shelf=philosophy |
| Psychology | shelf=psychology |
| Quotations | shelf=genref.quotations |
| Religion | shelf=religion |
| Science | shelf=science |
| Social Sciences | shelf=socsciences |
| Technology | shelf=technology |
Due to product and subscription variations, some clients may not have access to titles in a given categery. To obtain a list of categeories accessible to the current client, use the following URL:
http://xml.credoreference.com/xmlshelfnames.do?client=clientname&membertoken=token
To see the titles assigned to each category, see About our titles on corp.credoreference.com.
Offers access to an entry page search result. The structure for how the entry result is to be delivered in XML is given below. Each entry consists of an entry tag (<e>) with a corresponding <eid> number. Within each entry are a heading (<h>), body (<b>)and fancy heading (<fh>) these XML structures contain the raw HTML present on the destination site. Other tags are shown in the table below:
| Tag name | Description |
|---|---|
| <adjs> | adjacent entries |
| <b> | body |
| <cr> | copyright |
| <xcred> | Credo Reference credit message |
| <e> | entry |
| <eid> | entry id number |
| <fh> | fancy heading |
| <h> | heading |
| <links> | links/related entries |
| <nlinks> | number of links/related entries |
| <spub> | short publisher name |
| <sshelf> | short shelf name |
| <str> | strapline |
| <svol> | short volume name |
| <ed> | entry descriptor |
| <vt> | volume title |
Within <links> and <adjs>, the <eid> entry id number is present, also the heading and strapline information and finally the volume title for that entry. The structure is:
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE epage PUBLIC '-//xrefer//DTD XML Interface 2//EN' '/epage_2.dtd'>
<epage>
<eid></eid>
<h>?<str></str></h>
<b>?</b>
<sshelf></sshelf>
<svol></svol>
<spub></spub>
<nlinks></nlinks>
<fh></fh>
<cr></cr>
<xcred></xcred>
<links>
<ed>
<eid>?</eid>
<h>..<str></str></h>
<vt></vt>
</ed>
</links>
<adjs>
<ed>
<eid>?</eid>
<h>?<str></str></h>
<vt></vt>
</ed>
</adjs>
</epage>
All HTML tags delimiters are replaced with entity placeholders <, for < and >, for > (see the appendix: examples 1 and 2). The client converts these back to HTML (most XML software does this by default).
Entries may contain in-line links to other entries. These will be expressed as <a> elements within the entry body.
You should supply a URL as the "baseurl" parameter. This will be used as the base for these generated links. Credo Reference will append id=xxxxxx, so your base URL should end with either "?" (if it has no parameters, like "http://host/file?") or "&" (if it's of the form "http://host/file?x=y&a=b&").
Offers access to a page of search results. Search results given in XML will have the following format. This XML contains a results page together with Result descriptor individual entry results as shown in Example 3 in the Appendix. The results page contains the original search term, the total results delivered for that particular search term and also the results displayed on the page, this depends on how many the client wishes to display. So for Appendix - Example 3 below, the first 16 results have been displayed on page 1, page 2 will return results 17 to 30 and so on, total results returned are 43. This is then followed by the results descriptor results <rd id="1">, <rd id="2"> etc.
This can be used to display the context for search hits within a results page, or the first few words of the entry. The result descriptor page are as follows, each result is given an id number <rd id="1", <rd id="2"> etc, entry id number (<eid>), heading and section headings are provided, followed by an <ex> extract tag containing a few words with the original search term contained within. Volume title from which the result was returned is also given, and also relevancy of the search term and any additional heading information for the result contained within the <str> strapline tag.
<rpage>
<srch>search phrase</srch>
<from>start record</from>
<to>end record</to>
<tot>number of hits</tot>
<rd id="num">
<eid></eid>
<sh></sh>
<h>?<str></str></h>
<ex></ex>
<vt></vt>
<rel></rel>
</rd>
<rd id="num+1">
<eid></eid>
<sh></sh>
<h>?<str></str></h>
<ex></ex>
<vt></vt>
<rel></rel>
</rd>
<rd id="num+2">
<eid></eid>
<sh></sh>
<h>?<str></str></h>
<ex></ex>
<vt></vt>
<rel></rel>
</rd>
<rd id="num+3">
<eid></eid>
<sh></sh>
<h>?<str></str></h>
<ex></ex>
<vt></vt>
<rel></rel>
</rd>
<rd id="num+4">
<eid></eid>
<sh></sh>
<h>?<str></str></h>
<ex></ex>
<vt></vt>
<rel></rel>
</rd>
<rd id="num+5">
<eid></eid>
<sh></sh>
<h>?<str></str></h>
<ex></ex>
<vt></vt>
<rel></rel>
</rd>
</rpage>
Offers access to a page of Related Entries. This contains a list of related entry results given from the result descriptor, together with the initial search term, total number of related entries returned and the related entry results displayed on the page, this depends on how many the client wishes to display.
<xpage>
<srch></srch>
<from></from>
<to></to>
<tot></tot>
<vt></vt>
<rd id="0">?</rd>
<rd id="1">?</rd>
<rd id="2">?</rd>
.
.
</xpage>
Retrieves the jacket page of a particular title as an entry object. See Entry Object for details.
Version 2.0 of the Credo XML interface introduced new URLs. Those used prior to this version are deprecated and will no longer be supported in the future. The mappings from the deprecated to the current URLs are shown in this table.
| Deprecated URL | Current URL |
|---|---|
| token_get.jsp | xmltokenget.do |
| volumes.jsp | xmltitles.do |
| shelfnames.jsp | xmlshelfnames.do |
| results.jsp | xmlsearch.do |
| search_vols.jsp | xmlsearchtitles.do |
| entry.jsp | xmlentry.do |
| xrefs.jsp | xmlrelateds.do |
| jacket | xmljacket.do |