Skip to page content.

WorldCat Discovery API

Offer Resource

The offer resource provides access to item-level institution holdings in the WorldCat Discovery API. Up to 100 holdings can be retrieved for an OCLC number using the offer resource.

This resource is described in the terms of Schema.org as opposed to the traditional concept of a library holding. The use of "offer" is consistent with OCLC's linked data strategy to describe library data in the language of the Web.

URLs and Supported Operations

Operation Resource URL HTTP METHOD Response Code
Search https://beta.worldcat.org/discovery/offer/oclc/474685432?{parameters} GET 200
Read https://beta.worldcat.org/discovery/offer/oclc/{OCLC_Number}

 GET 200

HTTP Accept Types

The Discovery API supports the following mime types:

  • application/rdf+xml
  • text/plain
  • text/turtle
  • application/ld+json
  • application/json

This API uses OCLC's RDF-based data model. The primary vocabulary is based in schema.org with extensions for common components of bibliographic description.

To get a traditional web application view of the data, use the application/json mime type. This mime type will provide valid RDF within a traditional nested data structure. The response will provide a list of search results as the root object.

Parameters

Parameter Required? Description Expected/Sample Value
heldBy No

Limiter to restrict search results to items held by a given institution(s). For multiple values repeat the URL parameter.

OCLC Symbols

  • OCPSB
  • OCWMS
heldByGroup
 No

Limiter to restrict search results to items held by a given group(s). For multiple values repeat the URL parameter.

OCLC Group Symbols

  • OHLL
  • OSUL
heldInCountry No Limiter to restrict search results to items held by institutions within a single geo-political state defined by ISO country code.
  • US
  • AU
  • GB
itemsPerPage No Specify the number of results to return in the response.
  • 10 - default
  • 25
  • 50
  • 100
startIndex No Specify the starting position for the search response.
  • the first integer for the given range specified in itemsPerPage
useFRBRGrouping No Specify whether the response returns the representativve record for the FRBR group.
  • true - default
  • false
lat No

Defines the lattitude, up to 9 digits, to be used to limit a query to libraries within the distance from the defined geographical point.

Must be used with lon, distance and unit.
  • &lat=39.95674
lon No

Defines the longitude, up to 9 digits, to be used to limit a query to those items held by libraries within the distance from the defined geographical point.

Must be use with lat, distance and unit.
  • &lon=-82.934339&
distance No

Limits the query to those items held by libraries within the defined distance from the given latitude and longitude.

Must be use with lat, lon and unit.
  • &distance=10
unit No

Defines whether distance is measured in miles (M) or kilometers (K).

Must be used with lat, lon and distance.
  • &unit=M

Notes

Clients may only retrieve up to 100 offers for a given lookup request. The API will limit the number of holdings that can be retrieved. Requests to the service that request more than 100 offers or that paginate beyond the 100th offer for a given lookup criteria will receive an HTTP 400 Bad Request response.

Example Requests

  • https://beta.worldcat.org/discovery/offer/oclc/51969214?&heldInCountry=AU&heldBy=ataub
  • https://beta.worldcat.org/discovery/offer/oclc/51969214?&itemsPerPage=25&startIndex=25
  • https://beta.worldcat.org/discovery/offer/oclc/51969214?&lat=39.95674&lon=-82.934339&unit=M&distance=17