From WorldCat Developers' Network

Jump to: navigation, search

Contents

WorldCat Basic API

The WorldCat Basic API is available to any person for non-commercial use up to 1,000 queries a day.

  • Search WorldCat with OpenSearch and get RSS or Atom responses.
  • Find books, video, music and more in the WorldCat database
  • Get Titles, Authors, ISBNs and OCLC numbers
  • Get records in standard bibliographic citation formats (APA, Chicago, Harvard, MLA, and Turabian)
  • Get links back to WorldCat.org for more information including geographically-sorted Library information


What is WorldCat?

WorldCat is a global collection of library content contributed by over 70,000 libraries from around the world. It includes information of over 140 million items found in these libraries. Besides a massive collection of book titles, there are all kinds of items including videos, music, maps, magazines, special collections and many other kinds of material in over 470 languages.

Currently WorldCat can be searched for free at WorldCat.org. And today there are WorldCat widgets that enable anyone to embed WorldCat search results into their websites found at the WorldCat Affiliate Services site.


Signup for the WorldCat Basic API

Go to WorldCat Affiliate Services site and click on the WorldCat Basic API. There you'll be linked to the OCLC Service Configuration application for API key management. You will need to sign into (or create) a WorldCat.org Affliate account in order to sign in for the API key management.


Details on the WorldCat Basic API

For each query, Basic API users need to register for an access key or "wskey" which will be included in each query.

The form of an OpenSearch request is:
http://www.worldcat.org/webservices/catalog/search/opensearch?q=[search terms]&wskey=[your key]

The complete pattern for an OpenSearch request is:
http://worldcat.org/webservices/catalog/search/opensearch?q=[query]&format=[atom|rss]&start=[start position]&count=[maximum number of records to return]&cformat=[citation format]&wskey=[your key]

Only the query value "q" would be required. Queries are sent as strings of keywords. All other values are optional. The default values expected are: format=atom, start=1, count=10. The search result presented is limited to the first 100 records of that result.

The valid citation format values for the cformat field are apa, chicago, harvard, mla, turabian. If a valid cformat value is not included in the request, a formatted citation will not be supplied by default in the response. For more details, see the following notes about requesting formatted citations.

Some examples

A search for civil war, returning a result with the default Atom format, starting position, and count:
http://www.worldcat.org/webservices/catalog/search/opensearch?q=civil%20war&wskey=[key]

A search for civil war, returning a result in the RSS format, starting at position 6, with a count of 5 records:
http://www.worldcat.org/webservices/catalog/search/opensearch?q=civil%20war&format=rss&start=6&count=5&wskey=[key]

A search for civil war, returning a result in the Atom format, including an MLA-formatted citation for each record:
http://www.worldcat.org/webservices/catalog/search/opensearch?q=civil%20war&format=atom&cformat=mla&wskey=[key]

Sample responses

Sample RSS response
Sample Atom 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.


Interpreting Open Search Responses

Open search responses include title, the first author, a link, ISBN, 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 ...

  • 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, 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 first author.
  • 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, 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.
Personal tools