Response Details

Interpreting Open Search Responses

Open search responses include title, the first author, a link, ISBNs, ISSNs, LCCN and the OCLC number for the entire search result, whether the responses are in RSS or Atom format. For example, an Atom-formatted response:

<title>OCLC Worldcat Search: civil war</title>
<link href="http://worldcat.org/webservices/catalog/search/worldcat/opensearch?
q=civil+war&start=1&count=5&format=atom"/>
<subtitle>Search results for civil war at http://worldcat.org/webservices/catalog</subtitle>

The title offers a human-readable string that could be used to present a label for the search result, the link field contains a URL that represents the current search in the web service, and the subtitle gives a brief annotation for the search.

In addition, responses include some OpenSearch response elements that are used to extend the RSS and Atom syndication formats. The additional metadata can be helpful for result set context and navigation, including the result size, starting position, number of items, and the search terms. For example:

<opensearch:totalResults>322066</opensearch:totalResults>
<opensearch:startIndex>1</opensearch:startIndex>
<opensearch:itemsPerPage>5</opensearch:itemsPerPage>
<opensearch:Query role="request" searchTerms="civil war" startPage="1"/>

Other response elements differ, depending on the requested format.

For Atom responses, these elements are especially useful:

The link elements with rel attributes of alternate, self, first, next and last include pre-built URLs for navigation through the search result.

For each entry in the result set ...

• author includes the name of the primary author or a list of authors, if available in the record.
• title includes the item's title.
• link includes a pre-built URL for linking to the title in WorldCat.org.
• id includes the OCLC record number, as part of a WorldCat.org link. This link can be used to go directly to the record on WorldCat.org where a list of the nearby libraries that has the item and other information may be found.
• dc:identifier includes the ISBNs, ISSNs, or LCCNs, if present in the record
• oclcterms:recordIdentifier provides the OCLC number assigned to that specific record
• if a valid cformat value was included in the request, content includes an encoded HTML string in the requested citation format for the title. This field could be especially helpful for producing a standard format reading list from a web service response.

For RSS responses, these elements are especially useful for each "item" in the result:

• title includes the item's title.
• author includes the item's primary first author or a list of authors for the item, if available in the record..
• link includes a pre-built URL for linking to the title in WorldCat.org.
• guid includes the OCLC record number, as part of a WorldCat.org link. This link can be used to go directly to the record on WorldCat.org where a list of the nearby libraries that has the item and other information may be found.
• dc:identifier includes the ISBNs, ISSNs, or LCCNs, if present in the record
• oclcterms:recordIdentifier provides the OCLC number assigned to that specific record
• if a valid cformat value was included in the request, content:encoded includes an encoded HTML string in the requested citation format for the title. This field could be especially helpful for producing a standard format reading list from a web service response.

Requesting Formatted Citations

The API provides a way to obtain formatted bibliographic citations, in an HTML encoded form suitable for incorporation into a web application. The supported bibliographic citation formats are APA, Chicago, Harvard, MLA, and Turabian.

The formatted citation result is returned as a string of plain text, however it includes HTML formatting, so could be inserted directly into an HTML application. For example:

<p class="citation_style_TURABIAN">McPherson, James M. <i>Battle Cry of Freedom: The Civil War Era</i>. New York: Oxford University Press, 1988. </p>

this results in a formatted citation such as:

McPherson, James M. Battle Cry of Freedom: The Civil War Era. New York: Oxford University Press, 1988.

If 'all' is specified as the cformat, all available citation formats will be returned in a single string.

The CSS class included in the HTML "p" tag is intended to reference a stylesheet definition elsewhere in the HTML. Here are CSS definitions for the class references returned by the API.

Note that these citations are based on the reference standard for each style. However, formatting rules within a style can vary widely between applications and fields of interest or study. The specific requirements or preferences of your reviewing publisher, institution or organization should be applied.

In addition, some text formatting within citations may be lost or altered when copied into word processing programs or Web-based applications such as e-mail services.