XML Interface
Version 1.2

Contents

1. Introduction
2. Background
3. Organization of Credo Reference Data
4. Accessing Credo Reference Data
5. Authentication
6. Performing a Search
7. Limiting a Search to Selected Titles
8. Viewing a Result Entry
9. Viewing an Entry Section
10. Obtaining the Related Entries for an Entry
11. Obtaining the Book Categories
12. XML Object Descriptions
13. Entry XML
14. Links within an Entry
15. Entry XML DTD
16. Results XML
17. Results DTD
18. Related Entries XML
19. Related Entries DTD
20. List Shelves DTD
21. Appendix
22. Example 1 - Entry
23. Example 2 - Entry with Sections
24. Example 3 - Search Results
25. Example 4 - Related Entries
26. Sample Records

1. Introduction

2. Background

3. The organization of Credo Reference data

4. Accessing Credo Reference data

1. an authentication token obtained by logging in
2. a search result object containing references to a page of n entries retrieved by a query
3. an entry object
4. an object containing reference to a page of n related entries
5. a shelf list, listing the named book categories the user has access to

The following sections describe the syntax for requesting XML objects, the format of each XML object along with appropriate examples.

5. Authenticating the user to the Credo Reference XML interface

http://xml.xrefer.com/token_get.jsp?client=clientname&password=password

If the username and password are valid, the response of the token_get.jsp request will have a single element in the return:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE epage PUBLIC '-//xrefer//DTD XML Interface 1. 1//EN' '/rpage_1_1.dtd'>

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.

6. Performing a search

http://xml.xrefer.com/results.jsp?client=clientname&membertoken=token&searchterm=phrase&shelf=&resfrom=1&resto=10&maxchars=100

where

• clientname is the username of the logged-in client
• membertoken is the authentication token obtained by the token_get request
• searchterm is the initial search term or phrase
• resfrom is the first result to return in the result page
• resto is the final result to return in the result page
• shelf is an optional parameter that can be used to limit search results to a selected book category. See section 11 for the syntax to retrieve a list of the book categories available to the client.
• maxchars is the size of the extract (showing hits in context) that will be included in the <ex> element of each result.

7. Limiting a search to selected titles

http://xml.xrefer.com/results_by_vol.jsp?client=clientname&membertoken=token&searchterm=phrase&resfrom=1&resto=10&maxchars=100&volumes=vol-id-list

where

• clientname is the username of the logged-in client
• membertoken is the authentication token obtained by the token_get request
• searchterm is the initial search term or phrase
• resfrom is the first result to return in the result page
• resto is the final result to return in the result page
• volumes is a space-separated (%20) list of volume IDs to include in the search. Every Credo Reference title is assigned a numeric volume ID. The list of IDs is published in Librarian Admin
• maxchars is the size of the extract (showing hits in context) that will be included in the <ex> element of each result.

8. Requesting a specific entry

http://xml.xrefer.com/entry.jsp?client=clientname&membertoken=token&baseurl=http://www.xreferplus.com/entry.jsp?&xrefid=123456&secid=.-

Where

• baseurl is the URL to the www.xreferplus.com/entry.jsp page that will be prefixed to internal links inside each returned entry. The baseurl gives you the option of having links remain in the XML interface (by using a base of http://xml.xrefer.com/entry.jsp?) or of having the link use the HTML interface (by using a base of http://www.xreferplus.com/entry.jsp?). Leaving baseurl blank will make the href in the generated link a relative href. The baseurl is URL encoded like this: http%3A%2F%2Fwww.xreferplus.com%2Fentry.jsp%3F
• xrefid is the entry id (from the <eid> element in the result object for the desired entry.)
• secid is the section within the entry to return. Use .- (dot minus) to indicate you want the main entry, not a section
• links is an optional number of Related Entries to include in the entry object returned. Related Entries are relevance ranked entries, often from other books, that are related to the retrieved entry.
• adjacent is an optional number of adjacent entries to include in the entry object returned. Many books in Credo Reference are organized with alphebetical entries. Adjacent entries can help build a navigation list for paging sequentially from a retrieved entry, forward or backward.

The entry XML returned by the request is described in section 13.

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.xreferplus.com/entry.jsp?xrefid=entry identifier

9. Requesting a specific section within an entry

http://xml.xrefer.com/entry.jsp?client=clientname&membertoken=token&baseurl=&xrefid=123456&secid=16.-

which indicates that you have selected entry 123456 and section 16 within that entry.

10. Requesting a Related Entries list

http://xml.xrefer.com/xrefs.jsp?client=clientname&membertoken=token&xrefid=209845&shelf=&xreffrom=1&xrefto=10&maxchars=100

Where

• xrefid is the entry id (from the <eid> element in the result object for the desired entry.)
• xreffrom is the first related entry to return in the result page
• xrefto is the final related entry to return in the result page
• shelf is an optional parameter that can be used to limit results to a selected book category. See section 11 for the syntax to retrieve a list of the book categories available to the client.
• maxchars is the size of the extract (showing hits in context) that will be included in the <ex> element of each result.

The result object returned by the request is described in section 18.

11. Requesting a book category list

Each of the books in Credo Reference are organized into a number of broad categories (called shelves) listed here:

Due to product and subscription variations, some clients may not have access to books in a given categery. To obtain a list of categeories accessible to the current client, send the following URL:

http://xml.xrefer.com/shelfnames.jsp?client=clientname&membertoken=token

To see the titles assigned to each category, see About our titles on xrefer.com.

12. XML objects

13. Entry object

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE epage PUBLIC '-//xrefer//DTD XML Interface 1. 1//EN' '/epage_1_1.dtd'>

All HTML tags delimiters are replaced with entity placeholders &lt, for < and &gt, for > (see the appendix: examples 1 and 2). The client converts these back to HTML (most XML software does this by default).

14. Links within the body of an entry

You should supply a URL as the "baseurl" parameter. This will be used as the base for these generated links. Credo Reference will append xrefid=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&"). See Appendix - Example 2.

15. XML entry page DTD

<!ELEMENT epage (eid,h,b,sshelf,svol,spub,nlinks,fh,cr,xcred,links,adjs)>
<!ELEMENT eid (#PCDATA)>
<!ELEMENT h (#PCDATA|str)*>
<!ELEMENT str (#PCDATA)>
<!ELEMENT b (#PCDATA)>
<!ELEMENT sshelf (#PCDATA)>
<!ELEMENT svol (#PCDATA)>
<!ELEMENT spub (#PCDATA)>
<!ELEMENT nlinks (#PCDATA)>
<!ELEMENT fh (#PCDATA)>
<!ELEMENT cr (#PCDATA)>
<!ELEMENT xcred (#PCDATA)>
<!ELEMENT links (ed)*>
<!ELEMENT ed (eid,h,vt)>
<!ATTLIST ed id CDATA #IMPLIED>
<!ELEMENT vt (#PCDATA)>
<!ELEMENT adjs (ed)+>

16. Results object

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>

</rpage>

17. XML results page DTD

<!ELEMENT rpage (srch,from,to,tot,rd*)>
<!ELEMENT srch (#PCDATA)>
<!ELEMENT from (#PCDATA)>
<!ELEMENT to (#PCDATA)>
<!ELEMENT tot (#PCDATA)>
<!ELEMENT rd (eid,sid,sh,h,ex,vt,rel)>
<!ATTLIST rd id CDATA #REQUIRED>
<!ELEMENT eid (#PCDATA)>
<!ELEMENT sid (#PCDATA)>
<!ELEMENT sh (#PCDATA)>
<!ELEMENT h (#PCDATA|str)*>
<!ELEMENT ex (#PCDATA)>
<!ELEMENT vt (#PCDATA)>
<!ELEMENT rel (#PCDATA)>
<!ELEMENT str (#PCDATA)>

18. Related Entries object

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. See Appendix - Example 5.

<xpage>

</xpage>

19. XML Related Entries DTD

<!ELEMENT xpage (srch,from,to,tot,vt,rd+)>
<!ELEMENT srch (#PCDATA)>
<!ELEMENT from (#PCDATA)>
<!ELEMENT to (#PCDATA)>
<!ELEMENT tot (#PCDATA)>
<!ELEMENT vt (#PCDATA)>
<!ELEMENT rd (eid,sid,sh,h,ex,vt,rel)>
<!ATTLIST rd id CDATA #REQUIRED>
<!ELEMENT eid (#PCDATA)>
<!ELEMENT sid (#PCDATA)>
<!ELEMENT sh (#PCDATA)>
<!ELEMENT h (#PCDATA|str)*>
<!ELEMENT ex (#PCDATA)>
<!ELEMENT rel (#PCDATA)>
<!ELEMENT str (#PCDATA)>

20. List Shelves DTD

<!ELEMENT shelfnames (shelf)+>
<!ELEMENT shelf (#PCDATA)>

Appendix - Examples for the XML structures

These examples show the XML for various request types.

Example 1 - simple entry xml page

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE epage PUBLIC '-//xrefer//DTD XML Interface 1.  1//EN' 'http://xml.credoreference.com/dtds/epage_1_1.dtd'>

<epage>
    <eid>1405597</eid>
    <h>
      Great Red Spot (GRS)
      <str></str>
    </h>
    <b>&lt;a name="s.-"&gt;&lt;/a&gt;&lt;p&gt;An immense oval feature centered 22&amp;deg; south of Jupiter's equator. 
    It is variable in size and color. At its largest it can be 40 000 by 14 000 km, but at the time of the Voyager flybys, it was only slightly larger
    than the Earth. Its color - possibly associated with the conversion of phosphene into red phosphorus - has varied from pale pink to bright red.
    Often visible from Earth through small telescopes, it has been observed since the 17th century. Early explanations involved a solid island adrift
    in Jupiter's atmosphere or an atmospheric disturbance above a Jovian mountain or basin; the latter was disputed by evidence that it drifts in longitude.
    Infrared data from &lt;b&gt;Pioneer&lt;/b&gt; and Voyager spacecraft confirm that the spot is an anticyclonic high-pressure region 
    that is much colder than its surroundings and at a higher elevation. Examination of cloud motions in and around the GRS reveal that the spot rotates 
    counterclockwise with a period of about six days. The winds to the north of the spot are blowing to the west, the winds to the south move toward 
    the east.&lt;/p&gt;</b>
    <sshelf>science</sshelf>
    <svol>hcdastr</svol>
    <spub>hprcoln</spub>
    <nlinks>8</nlinks>
    <fh>Great Red Spot (GRS)</fh>
    <cr>Collins Dictionary of Astronomy, &amp;copy; Market House Books Ltd. 1994, 2000</cr>      
    <xcred>Powered by credoreference.com</xcred>      
    <links>
      <ed> 
        <eid>1407671</eid>
        <h>
          Voyager probes
          <str></str>        
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed> 
        <eid>1115525</eid>
        <h>
          Voyager probes
          <str></str>        
        </h>
        <vt>The Hutchinson Encyclopedia, Helicon</vt>
      </ed>
      <ed> 
        <eid>1405594</eid>
        <h>
          Great Dark Spot
          <str></str>        
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed> 
        <eid>3313984</eid>
        <h>
          Voyager probes
          <str></str>        
        </h>
        <vt>The Macmillan Encyclopedia</vt>
      </ed>
      <ed> 
        <eid>1405945</eid>
        <h>
          Jupiter
          <str></str>        
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
    </links>
    <adjs>
      <ed>
        <eid>1405592</eid>
        <h>
          great circle
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405593</eid>
        <h>
          Great Cluster in Hercules (M13, NGC 6205)
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405594</eid>
        <h>
          Great Dark Spot
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405595</eid>
        <h>
          greatest elongation (GE)
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405596</eid>
        <h>
          Great Observatories
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405597</eid>
        <h>
          Great Red Spot (GRS)
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405598</eid>
        <h>
          Great Rift
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405599</eid>
        <h>
          Great Square of Pegasus
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405600</eid>
        <h>
          Great Wall
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405601</eid>
        <h>
          Greek alphabet
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
      <ed>
        <eid>1405602</eid>
        <h>
          Green Bank
          <str></str>
        </h>
        <vt>Collins Dictionary of Astronomy</vt>
      </ed>
    </adjs>  
</epage>

To see how this entry looks in the www.xreferplus.com HTML interface, log into http://www.xreferplus.com and then see:

http://www.xreferplus.com/entry.jsp?xrefid=1405597&secid=.-

Example 2 - entry xml page containing sections

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE epage PUBLIC '-//xrefer//DTD XML Interface 1. 1//EN' '/dtds/epage_1_1.dtd'>

Based on example taken from xreferplus.com at:

Example 3 - results xml page

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE rpage PUBLIC '-//xrefer//DTD XML Interface 1. 1//EN' '/dtds/rpage_1_1.dtd'>

Section results are also taken in account, where the result actually appears within a section of the xml, for example:

Based on example taken from xreferplus.com at:

Example 4 - Related Entries xml page

<?xml version="1.0" encoding="iso-8859-1"?> 
<!DOCTYPE xpage PUBLIC '-//xrefer//DTD XML Interface 1.  1//EN' 'http://xml.credoreference.com/dtds/xpage_1_1.dtd'>
<xpage>
  <srch>Great Red Spot (GRS)</srch>
  <from>1</from>
  <to>8</to>
  <tot>8</tot>
  <vt>Collins Dictionary of Astronomy</vt>
    <rd id="1"> 
      <eid>1115525</eid>
      <sid></sid>
      <sh></sh>
      <h>
        Voyager probes
        <str></str>  
      </h>
      <ex>Two US space probes.  Voyager 1 , launched on 5 September 1977, passed the planet Jupiter in March 1979, and reached 
      Saturn in November 1980.  Voyager 2  was launched earlier, on 20 August...</ex>
      <vt>The Hutchinson Encyclopedia, Helicon</vt>  
      <rel>100</rel>
    </rd>
    <rd id="2"> 
      <eid>1405594</eid>
      <sid></sid>
      <sh></sh>
      <h>
        Great Dark Spot
        <str></str>  
      </h>
      <ex>A prominent feature in Neptune's atmosphere, similar in many ways to Jupiter's  Great Red Spot . The Great Dark Spot
      measures roughly 12 000 km by 8000 km and, scaled down by the same factor...</ex>
      <vt>Collins Dictionary of Astronomy</vt>  
      <rel>100</rel>
    </rd>
    <rd id="3"> 
      <eid>3313984</eid>
      <sid></sid>
      <sh></sh>
      <h>
        Voyager probes
        <str></str>  
      </h>
      <ex>Two highly successful US  planetary probes  launched in 1977 towards the outer planets. Voyager 1 approached Jupiter 
      in March, 1979, then flew towards Saturn, which it reached in November,...</ex>
      <vt>The Macmillan Encyclopedia</vt>  
      <rel>100</rel>
    </rd>
    <rd id="4"> 
      <eid>1405945</eid>
      <sid></sid>
      <sh></sh>
      <h>
        Jupiter
        <str></str>  
      </h>
      <ex>The largest planet, orbiting the Sun at a mean distance of 5.2 AU in 11.86 years. It has an equatorial diameter of 
      142 985 km (11 times that of the Earth) and a polar diameter of 133 718 km....</ex>
      <vt>Collins Dictionary of Astronomy</vt>  
      <rel>100</rel>
    </rd>
    <rd id="5"> 
      <eid>1406694</eid>
      <sid></sid>
      <sh></sh>
      <h>
        Pioneer probes
        <str></str>  
      </h>
      <ex>A series of US Solar-System probes. Pioneers 1-3 were intended lunar probes in 1958, although Pioneer 2 suffered 
      launch failure and Pioneers 1 and 3 fell short of the Moon but did measure the...</ex>
      <vt>Collins Dictionary of Astronomy</vt>  
      <rel>100</rel>
    </rd>
    <rd id="6"> 
      <eid>1406937</eid>
      <sid></sid>
      <sh></sh>
      <h>
        Red Spot
        <str></str>  
      </h>
      <ex>See   Great Red Spot .  ...</ex>
      <vt>Collins Dictionary of Astronomy</vt>  
      <rel>100</rel>
    </rd>
    <rd id="7"> 
      <eid>1407062</eid>
      <sid></sid>
      <sh></sh>
      <h>
        Saturn
        <str></str>  
      </h>
      <ex>The sixth major planet and, with an equatorial diameter of 120 537 km, the second largest. It orbits at a distance of
       between 9.01 and 10.04 AU from the Sun every 29.46 years;  oppositions ...</ex>
      <vt>Collins Dictionary of Astronomy</vt>  
      <rel>100</rel>
    </rd>
</xpage>

Based on example taken from xreferplus.com at:

Full length XML Sample Data

For a full length example of entry page, results page and related entries page xml please see the following files: