View source

= WorldCat Search API: Background =

Search with OpenSearch or SRU and get RSS, Atom, MARC XML or Dublin Core responses.

* Find books, video, music and more in the WorldCat database
* Send searches in OpenSearch or SRU CQL syntax
* Get OpenSearch responses in RSS or Atom format
* Get SRU responses in MARC XML or Dublin Core
* Get MARC XML content for a single OCLC record
* Get geographically-sorted Library information (institution name, location, and an OPAC link) in requests for single records 
* Get records in standard bibliographic citation formats (APA, Chicago, Harvard, MLA, and Turabian)

<div style="color:red; border: 1px solid black; padding: .5em;">
<span style="font-weight: bold;">API requests require the addition of an access key, provided by OCLC.</span> Include your assigned key as a "wskey" parameter in each request to the API, as shown in the example links on this page.
</div>

= Using OpenSearch =

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

The complete pattern for an OpenSearch request is:<br/>
<nowiki>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]</nowiki>

Only the query value "q" is required. Queries are sent as strings of keywords. All other values are optional. The default values are: format=atom, start=1, count=10. 

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 is not supplied by default in the response.  For more details, see the following notes about [[SearchAPIDetails#Requesting_Formatted_Citations|requesting formatted citations]].

'''Some examples'''

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

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

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

'''Sample responses'''

[[SearchAPISampleRSS|Sample RSS response]]<br/>
[[SearchAPISampleAtom|Sample Atom response]]

= Using SRU =

The simplest form of an SRU request is:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/search/sru?query=[search terms]&wskey=[key]</nowiki>

The system-supplied defaults are keyword search, MARC XML format results, starting position 1, maximum records 10, and sort order of "relevance". 

The query terms can be specified in CQL syntax, to select other indexes, relations, and operators. For example:
* srw.kw%3D%22civil%20war%22 -- a keyword search for records matching ''civil war''

Other request values that can be set in the request include:
* recordSchema -- determines the result format, and can be MARC XML (info%3Asrw%2Fschema%2F1%2Fmarcxml) or Dublin Core (info%3Asrw%2Fschema%2F1%2Fdc)
* startRecord -- the starting position of the result set
* maximumRecords -- the maximum number of records to return in a single request
* sortKeys -- specifies how the result is sorted.  Choose from relevance, Title, Author, Date, Library Count, Score, or OCLC Number.  The default sort direction is "ascending"; to switch to descending add ",,0" to the sortKey.  Separate combined sortKeys with a space.
* frbrGrouping -- values are "on" (default) or "off".  When "on" or not specified, search results group together records of similar editions and present only the top held record as the representative record for that group.  This is sometimes referred to as a "FRBRized" result set.  To see separate records for editions, set this parameter to "off".

'''Some examples'''

The simplest formulation of an SRU request, as a keyword search for ''civil war'' returning all default response properties:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/search/sru?query=civil%20war&wskey=[key]</nowiki>

A CQL keyword search for ''civil war'' with results returned in Dublin Core format:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/search/sru?query=srw.kw%3D%22civil%20war%22&recordSchema=info%3Asrw%2Fschema%2F1%2Fdc&wskey=[key]</nowiki>

A subject search for ''globalization'' with MARC XML results sorted in descending Date order:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/search/sru?query=srw.su%3D%22globalization%22&sortKeys=Date,,0&wskey=[key]</nowiki>

A search for the author ''mann'' and title ''faustus''<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/search/sru?query=srw.au+%3D+%22mann%22+and+srw.ti+%3D+%22faustus%22&wskey=[key]</nowiki>

A search for the keyword ''civil war'' and the subject ''antietam'' or ''sharpsburg''
<nowiki>http://www.worldcat.org/webservices/catalog/search/sru?query=srw.kw+%3D+%22civil+war%22+and+%28srw.su+%3D+%22antietam%22+OR+srw.su+%3D+%22sharpsburg%22%29&wskey=[key]</nowiki>

'''Sample Responses'''

[[SearchAPISampleMARCXML|Sample MARC XML Response]]<br/>
[[SearchAPISampleDC|Sample Dublin Core Response]]

'''Other SRU Resources'''

* the [http://worldcat.org/webservices/catalog/ SRU Explain] link on the API home page provides a list of supported indexes
* the [http://www.loc.gov/standards/sru/cql-bibliographic-searching.html SRU CQL] includes detailed documentation for CQL queries
* the [http://www.oclc.org/support/documentation/firstsearch/z3950/z3950_databases/specs/worldcat.htm OCLC WorldCat Z39.50 guide] can be useful, in particular for indexes, allowed values, and such.

Note that other SRU standard request parameters are supported and can be included in the URL, but they are not required as default values will be supplied. The name/value pairs are: version=1.1, operation=searchRetrieve, and resultSetTTL=300.

= Requesting a Single Bibliographic Record =

To retrieve a single record in MARC XML format, use a "content" request and an OCLC number or ISBN rather than a search. Content requests are sent with this URL pattern:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/[oclc number]?wskey=[key]</nowiki>
<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/isbn/[isbn]?wskey=[key]</nowiki>

For example:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/15550774?wskey=[key]</nowiki>
<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/isbn/078946988X?&wskey=[key]</nowiki>

= Requesting Library Locations =

Content requests will return library location information sorted by geographic proximity if the request includes the "/content/libraries/" resource identifier in the path before the OCLC record number or ISBN.

By default, the API will attempt to resolve the IP address of the server that is making the connection to a geographic location and show the nearest libraries that hold the item.

If the request includes a "location" parameter with the name or code for a state, province, or country, or with a postal code, the API will attempt to resolve that to a geographic location.

If the request includes an "ip" parameter with an end user’s IP address, the API will attempt to resolve that to a geographic location and return nearby libraries.  

If the request includes "lat" and "lon" parameters with valid latitude and longitude coordinates, the API will return the list starting with the library closest to that position.

If the request includes a "libtype" parameter, matching libraries will be limited by the library type, where 1 = academic, 2 = public, 3 = government, and 4 = other.

If the request does not include a record identifier, the API will return all known libraries starting with the library closest to the user's position.

You can navigate through sets of library locations using the startLibrary and maximumLibraries parameters.

The request pattern is:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/[oclc number]?location=[postal code|state,province,country name or code]&startLibrary=[number]&maximumLibraries=[number]&libtype=[n]&wskey=[key]</nowiki>

or, for an ISBN:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/isbn/[isbn]?location=[postal code|state,province,country name or code]&startLibrary=[number]&maximumLibraries=[number]&libtype=[n]&wskey=[key]</nowiki>

or, without a record identifier:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/?location=[postal code|state,province,country name or code]&startLibrary=[number]&maximumLibraries=[number]&libtype=[n]&wskey=[key]</nowiki>

'''Some examples'''

Near the location associated with the IP address of the connecting client application:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/15550774?wskey=[key]</nowiki>

Near the zip code 94002:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/15550774?location=94002&wskey=[key]</nowiki>

Public libraries in the state of Maine:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/15550774?location=maine&libtype=2&wskey=[key]</nowiki>

Near the latitude/longitude coordinates 37.502508/-122.22702:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/15550774?lat=37.502508&lon=-122.22702&wskey=[key]</nowiki>

In the Netherlands (by country code), starting at location 5 and including a maximum of 5 locations:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/15550774?location=nl&startLibrary=5&maximumLibraries=5&wskey=[key]</nowiki>

Near the location associated with the IP address 153.40.170.1:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/15550774?ip=153.40.170.1&wskey=[key]</nowiki>

Near the zip code 10029, but if that location value is not recognized, then near the location associated with the IP address 153.40.170.1:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/15550774?ip=153.40.170.1&location=10029&wskey=[key]</nowiki>

The resulting library location information is currently represented in XML following the [http://www.loc.gov/standards/iso20775/N121_ISOholdings_v4.xsd ISO 20775 Holdings schema] and includes the OCLC institution symbol, institution name, physical location, and links to online resources. For example:

<pre>
<holding>
	<institutionIdentifier>
		<value>CZP</value>
		<typeOrSource>
			<pointer>http://worldcat.org/registry/institutions/</pointer>
		</typeOrSource>
	</institutionIdentifier>
	<physicalLocation>Peninsula Library System</physicalLocation>
	<physicalAddress>
		<text>San Mateo, CA 94403 United States</text>
	</physicalAddress>
	<electronicAddress>
		<text>http://www.worldcat.org/wcpa/oclc/8114241?
		page=frame&amp;url=http%3A%2F%2Fcatalog.plsinfo.org%2Fsearch%2Fi0380641135
		&amp;title=Peninsula+Library+System&amp;linktype=opac
		&amp;detail=CZP%3APeninsula+Library+System%3APublic
		&amp;qt=affiliate&amp;ai=wcapi</text>
	</electronicAddress>
	<holdingSimple>
		<copiesSummary>
			<copiesCount>1</copiesCount>
		</copiesSummary>
	</holdingSimple>
</holding>
</pre>

= Requesting a Library Catalog URL for a specific library and record =

If you have an ISBN or OCLC number for a record and want to get its Library Catalog URL for a specific OCLC Library, construct your request this way:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/isbn/[isbn]?oclcsymbol=[library symbol]&wskey=[key]</nowiki><br/>
or<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/[oclc number]?oclcsymbol=[library symbol]&wskey=[key]</nowiki>

For example:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/isbn/0026071800?oclcsymbol=OSU&wskey=[key]</nowiki>

The API response will either be a Holding structure, as shown above, for just your designated library, or a "no holdings found" diagnostic.

You can provide more than one OCLC symbol in the request. Separate multiple values with a comma, for example:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/libraries/15550774?oclcsymbol=OSU,STF&wskey=[key]</nowiki>

= 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.  Requests include an OCLC identifier and an optional citation format (if the format is not specified, an MLA-formatted citation is returned).

'''Some examples'''

The simplest formulation of a citation request includes just the OCLC identifer, and an MLA citation is returned:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/citations/15550774?wskey=[key]</nowiki>

To specify a citation format, include a cformat parameter with one of these valid values: apa, chicago, harvard, mla, turabian, or all<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/citations/15550774?cformat=turabian&wskey=[key]</nowiki>

The 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:<br/>
<pre>
<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>
</pre>
which results in a formatted citation such as:
<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>

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. [[SearchAPICitationCSS|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 will include title, link, and description elements for the entire search result, whether the responses are in RSS or Atom format. For example, an Atom-formatted response:

<pre>
<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>
</pre>

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:

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

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 from the MARC 245 field.
* 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. As other OCLC web services emerge, this ID will be an important key for input into other types of requests (for example, to get the reviews for an item, to add it to a list, etc.)
* 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.
* summary includes a summary of the title from the MARC 520 field. It isn’t available for all records. 

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

* title includes the item's title from the MARC 245 field.
* 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. As other OCLC web services emerge, this ID will be an important key for input into other types of requests (for example, to get the reviews for an item, to add it to a list, etc.)
* 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.
* description includes a summary of the title from the MARC 520 field. It isn’t available for all records.

= Interpreting SRU Responses =

SRU Responses will include a number of fields that are useful for setting the context of the result set, and result navigation:

    * numberOfRecords includes a count of the total result set
    * nextRecordPosition shows the starting position of the next item in the result
    * query includes the search string in CQL format
    * maximumRecords identifies the maximum records returned per request
    * startRecord shows the starting position of this request 

Other response elements differ, depending on the requested bibliographic record format.

For Dublin Core responses, these elements are useful:

* oclcterms:recordIdentifier includes LCCNs and OCLC identifiers.  OCLC identifiers can be selected based on the absence of an xsi:type attribute in the oclcterms:recordIdentifier element. 
* dc:identifier includes ISBNs
* dc:title includes the item’s title from the MARC 245 field.
* dc:creator includes creator name(s)
* dc:contributor includes name(s) of editors, translators, etc.
* dc:type includes a string identifying the type of material, which (depending on the MARC record) can also include form and genre
* dc:publisher includes the publication place and publisher name
* dc:date includes the publication date
* dc:description includes note fields from the MARC record
* dc:subject includes subject headings from the MARC record 
* dc:relation includes links to related web resources from the MARC 856 field

Those who favor the MARC XML response may already have stylesheets available that can transform the MARC record into their preferred format. We're providing a response in the Library of Congress' MARC 21 XML format ([http://www.loc.gov/standards/marcxml/]), and there are a variety of existing transformation programs and stylesheets available for converting this data format.

= Specifying Service Levels =

The [[SearchAPIServiceLevels | Service Levels]] available to a system that uses the Search API are controlled, in part, by a parameter added to each API Request.  

The parameter name is ''servicelevel'' and it currently accepts two values, ''default'' and ''full''.

If the parameter is not supplied in a request, the API system will apply the ''default'' service level.

Consult the [[SearchAPIServiceLevels | Service Levels]] documentation to determine the differences in  available indexes and displays between the two levels.

'''Some examples'''

A request for a single record at the full service level:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/content/8114241?servicelevel=full&wskey=[key]</nowiki>

An SRU search request at the default service level:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/search/sru?query=srw.kw%3D%22civil%20war%22&servicelevel=default&wskey=[key]</nowiki>

An OpenSearch request at the full service level:<br/>
<nowiki>http://www.worldcat.org/webservices/catalog/search/opensearch?q=civil%20war&wskey=[key]&servicelevel=full</nowiki>

<hr>
API Background | [[SearchAPIDemos|Sample Apps]] | [[SearchAPIFAQ|FAQ]] | [[SearchAPIIssues|Known Issues]] | [[SearchAPIServiceLevels|Service Levels]] |  [[SearchAPIWhoCanUse|Who can use the web service?]] | [[SearchAPITerms|Service Terms and Conditions]] | [[PlannedInstallDates|Planned Install Dates]]