WorldCat Metadata API Sandbox Testing

The WorldCat Metadata API does not have a true sandbox environment for testing. Instead, you will be issued a sandbox Web Service Key (WSKey) that is associated with a fake institution used for testing purposes. However, even when using a sandbox WSKey, you will still be making changes to the production data in WorldCat. For this reason, please make note of the following ground rules for sandbox use of the WorldCat Metadata API.

Some operations are safer than others

Changes to the following types of records are safe when using a sandbox WSKey:

  1. Set/unset holdings
  2. Create, Read, Update and delete LBD information attached to these records

When working with holdings data or or local bibliographic data, the changes will be specific to an institution. In this case, the sandbox institution. Your changes to these kinds of records will not affect your production data or that of another institution.

Holdings Operations are limited to test records

Operations on holdings are restricted for the sandbox institution.  These operations are blocked unless the record's transcribing agency (the 040 $c subfield) is a test institution. This prevents Sandbox WSKeys from modifying non-test records. Developers must interact with a specific list of test records.

Caution is required for changes to Bibliographic Records

When you make changes to Bibliographic Records through the WorldCat Metadata API, you are changing the production data for a cooperative catalog. This means that updates to bibliographic records held by multiple institutions will affect all holding libraries.

To mitigate the risk for your development and testing of the Metadata API, when you request a WSKey for this service you will be assigned a set of 5 records that you can use for testing purposes. These records will be uniquely yours so they are the best records to use for testing purposes.

Any new bibliographic records created with a Sandbox WSKey will be added to the live production copy of WorldCat even if you are using a sandbox WSKey. The best way to learn how to use the Bibliographic Record service is to first become familiar with the record formats and data model through the Update functionality against the sandbox records you are assigned.

Merging operations

Please note that the WorldCat Metadata API also simplifies your interaction with WorldCat Bibliographic Records. There are many complex matching algorithms that take place behind the update and create operations that OCLC uses to ensure the high quality and integrity of the WorldCat data set. This means that if you modify one of your sandbox records in such a way that you change certain data elements, the sandbox record may be merged into other producion records used by your institution or other OCLC members. Consequently, please do not create or update the data in the following fields of your sandbox test records in ways that they will match and potentially merge with existing WorldCat records:

  • Title statements
  • Author/Creator statements
  • Identifiers such as ISBNs and ISSNs
  • OCLC numbers


Help us with debugging: transaction IDs

To better assist us with helping you debug issues you encounter, follow the reccommendations in the guide to Getting Help Debugging Your Code when requesting assistance. Additionally, send a transactionID parameter with your requests when you are testing. A transactionID is is an arbitrary string not to exceed 200 characters which is meaningful to the caller. You can create your own transactionID by stringing together elements. For example a transactionID might be built by combining

  • OCLC Symbol being worked with or if using Sandbox OCLC Symbol of institution doing testing
  • date and time
  • principalID of user performing operation