WMS Availability API transition resources
OCLC recommends that customers begin transitioning to the Access Options API as soon as possible. The Access Options API copy-availability endpoint replaces all uses of the WMS Availability API.
This transition aligns the behavior of the API with the behavior of availability in the Discovery interface, so the availability your applications display matches what patrons see in Discovery.
The WMS Availability API supports OAuth 2.0 and the Access Options API supports OAuth 2.0 only, so applications still authenticating with HMAC must move to OAuth 2.0 as part of this transition.
About the Access Options API copy-availability endpoint
Modern authentication technology patterns of OAuth 2.0 to support different types of client applications.
A uniform, understandable data model using JSON for data exchange, replacing the SRU/OPAC XML response.
Availability that matches Discovery: availability in the API follows the same behavior as availability in the Discovery interface.
Copy-level results: each record represents one physical copy, with its location, call number, status, and an available flag you can use directly.
Summary holdings and public notes: in addition to copy-level records, the response includes a summary holdings statement and publicNotes for the institution's holdings of the item, which were not available in the WMS Availability API.
Easier troubleshooting and support: the Access Options API has more robust logging and monitoring, which helps OCLC Support and your team diagnose and resolve problems faster.
Part of a single API that also provides OPAC links, e-holdings, open access links, and local services links, so one integration can support more of your discovery experience.
Recommended transition paths
All current uses of the WMS Availability API transition to the Access Options API.
| Current WMS Availability API use | Recommended alternative |
|---|---|
| Display shelf availability of an item by OCLC number | Access Options API copy-availability |
| Display copy location, shelving location, and call number | Access Options API copy-availability |
| Display copy-level status, enumeration, and chronology | Access Options API copy-availability |
What is changing
Authentication and request basics
| WMS Availability API | Access Options API copy-availability | |
|---|---|---|
| Base URL | https://worldcat.org/circ/availability/sru | https://discovery.api.oclc.org |
| Endpoint | GET /service | GET /access-options/copy-availability |
| Authentication | OAuth 2.0 (client credentials or authorization code); HMAC being deprecated | OAuth 2.0 only (client credentials or authorization code) |
| Token URL | https://oauth.oclc.org/token | https://oauth.oclc.org/token (no change) |
| WSKey scope | WMS_Availability | accessOptions |
| Institution | Required x-registryId query parameter that must match the institution of the access token | No institution parameter. The institution comes from the access token. |
| Item identifier | Required query parameter using an index prefix, for example no:15703846 | Required oclcNumber parameter, a positive whole number, for example 15703846 |
| Response format | XML (SRU searchRetrieveResponse containing OPACXML) | JSON (application/json) |
| Error format | SRU diagnostics in XML | RFC 7807 problem details in JSON |
Action required: Request a WSKey with the accessOptions scope, before you begin testing. Requests made with a token that has only the WMS_Availability scope will not be authorized.
Request parameters
| WMS Availability API | Access Options API | Notes |
|---|---|---|
| x-registryId (required) | Not used | Institution is determined from the access token. |
| query (required), for example no:15703846 | oclcNumber (required) | Pass the OCLC number only, without the no: prefix. |
| x-return-group-availability | Not available | Group availability is not returned. |
| x-determine-renewable | Not available | Renewable status is not returned. |
| x-return-item-container | Not available | Container information is not returned. |
Response structure
The response changes from a MARC bibliographic record with nested holdings and circulation items to a flat list of copies.
No bibliographic record. The WMS Availability API returned the full MARC record with every response. The Access Options API returns availability data only. Use the WorldCat Metadata API or WorldCat Search API if you need bibliographic data.
One record per copy. In WMS Availability, a holding could contain several circulation items. In copy-availability, each entry in records is a single copy and its holdingParts array always contains exactly one element.
numberOfRecords means something different. In WMS Availability it counted bibliographic records and was typically 1. In copy-availability it is the number of copy records returned. Applications that read this value to decide whether holdings exist must be updated.
New: summary holdings and public notes. The response now includes a top-level summary (summary holdings statement for the institution's holdings of the item) and publicNotes (public note for those holdings). Each copy can also carry its own holdingPublicNote. Display these in your interface to give patrons holdings context without a separate lookup.
Empty fields are omitted. Fields with no value are left out of the JSON rather than returned as empty strings.
Failures are not partial. If availability cannot be retrieved, the request returns a 500 rather than a partial set of records.
Field mapping
| WMS Availability API (XML) | Access Options API (JSON) | Notes |
|---|---|---|
| controlfield tag="001" in bibliographicRecord | oclcNumber | Top-level string. |
| numberOfRecords | numberOfRecords | Counts copies now, not bibliographic records. |
| holding/typeOfRecord (u, v, x, y) | records[].format | Returned as text: Unknown, Multipart item, Single part item, Serial item. |
| holding/nucCode | records[].location.holdingLocation | Institution symbol. |
| holding/localLocation | records[].location.sublocationCollection | |
| holding/shelvingLocation | records[].location.shelvingLocation | |
| temporaryLocation | records[].location | Temporary location is no longer a separate element. If a copy is in a temporary location, the location node reflects the temporary location. Applications no longer have to check both fields. |
| holding/callNumber (single string) | records[].callNumber | Now an object: displayCallNumber, classificationPart, itemParts. Omitted if the copy has no call number. |
| circulation/itemId | records[].holdingParts[0].pieceDesignation | Barcode. |
| circulation/availableNow value="1" or "0" | records[].holdingParts[0].available | Now a boolean. |
| enumAndChron, volumes/volume | records[].holdingParts[0].status | Enumeration and chronology are part of the display status statement, not separate fields. |
| circulation/onHold value="1" or "0" | records[].holdingParts[0].holdingStatusCode (ON_HOLD) and records[].holdingParts[0].status | Hold status is no longer a separate flag. A copy on hold returns ON_HOLD as its status code, and the display status statement reflects it. |
| renewable | Not available | No longer returned. The x-determine-renewable option is also not available. |
| holdQueueSize | Not available | No longer returned. |
| container | Not available | No longer returned. The x-return-item-container option is also not available. |
| Group availability | Not available | No longer returned. The x-return-group-availability option is also not available. |
| copyNumber | Not available | No longer returned. |
| encodingLevel, receiptAcqStatus, generalRetention, completeness, dateOfReport | Not available | Holdings-level MARC fields are no longer returned. If you need MARC LHR holdings data, use the /my-holdings endpoint in the WorldCat Discovery API. |
| Not available | records[].holdingParts[0].holdingStatusCode | New. Circulation status code for the copy. See "Holding status codes" below. |
| Not available | records[].holdingParts[0].holdingPublicNote | New. Public note for the copy. |
| Not available | summary | New. Summary holdings statement for the institution. |
| Not available | publicNotes | New. Public note for the institution's holdings of the item. |
Holding status codes
holdingStatusCode gives a single circulation status for the copy and takes the place of the separate onHold flag. Use available for a simple yes or no, and holdingStatusCode when you need to show why a copy is not available.
| Value | Meaning |
|---|---|
| AVAILABLE | The copy is available. |
| NOT_AVAILABLE | The copy is not available. |
| CHECKED_OUT | The copy is checked out. |
| ON_HOLD | The copy is on hold. |
| ON_ORDER | The copy is on order. |
| CIRC_INFO_UNAVAILABLE | Circulation information is not available for the copy. |
The available flag is true only when holdingStatusCode is AVAILABLE. Handle unrecognized values gracefully, since additional status codes may be added.
Applications that need MARC LHR holdings data
The WMS Availability API returned holdings-level MARC fields. If your application needs MARC LHR holdings data, use the /my-holdings endpoint in the WorldCat Discovery API.
Error handling
Error responses change from SRU diagnostic XML to JSON problem details with a type, title, and detail, and an invalidParams array when validation fails.
| Condition | WMS Availability API | Access Options API |
|---|---|---|
| Missing or invalid required parameter | 400, SRU diagnostic info:srw/diagnostic/1/7 naming the parameter | 400, problem details, for example INVALID_QUERY_PARAMETER_VALUE with detail "oclcNumber must be a positive whole number" |
| Institution does not match token | 403, SRU diagnostic 68 | Not applicable. There is no institution parameter to mismatch. 403 is returned for an invalid or unauthorized client. |
| Group availability for a non-grouped institution | SRU diagnostic 2 | Not applicable. |
| Unsupported HTTP method | 405, HTML error page | 405, JSON problem details (NOT_ALLOWED) |
| Unsupported Accept header | Not documented | 406, JSON problem details (NOT_ACCEPTABLE). Send Accept: application/json or omit the header. |
| Server error | 500 | 500, including when availability cannot be retrieved. No partial results. |
Update any code that parses the SRU diagnostics element to read the JSON type and detail fields instead.
Example
WMS Availability API request
GET https://worldcat.org/circ/availability/sru/service?x-registryId=128807&query=no:23218965
Authorization: Bearer {access_token}
Access Options API request
GET https://discovery.api.oclc.org/access-options/copy-availability?oclcNumber=23218965
Authorization: Bearer {access_token}
Accept: application/json
Access Options API response
{
"numberOfRecords": 1,
"oclcNumber": "23218965",
"summary": "Local Holdings Available.",
"publicNotes": "My public notes",
"records": [
{
"format": "Single part item",
"location": {
"holdingLocation": "IQUU",
"sublocationCollection": "Second Floor",
"shelvingLocation": "Zimmerman Second Floor"
},
"callNumber": {
"displayCallNumber": "F787 .H53 1991",
"classificationPart": "F787",
"itemParts": [".H53", "1991"]
},
"holdingParts": [
{
"pieceDesignation": "A14429340048",
"available": true,
"holdingStatusCode": "AVAILABLE",
"status": "Available",
"holdingPublicNote": "has dust jacket"
}
]
}
]
}
Support for your transition
Our API team is committed to supporting your transition from the WMS Availability API to the Access Options API.
Learn from an API expert
OCLC APIs Office Hours. Office Hours provide an opportunity for you to discuss questions related to your institution's transition with OCLC API experts. View past OCLC APIs Office Hours Register for future Office Hours
Help for specific transition tasks
Access Options API technical documentation
WMS Availability API technical documentation
Personal assistance when you need it