OpenURL Request

Building a query

A URL query used to access the WorldCat Knowledge Base API can be broken down into three groupings:

• Journal and book level information 
• Article level information 
• WorldCat Knowledge Base API specific commands and filters 

The query and associated parameters follow the OpenURL standard with the following caveats:

Response Format:

By default, the response format is set to JSON, however, using the OpenURL ServiceType entity, XML can also be requested as a response type. To invoke the different response types the following key-value pairs can be used:

svc_id=json

or

svc_id=xml

Internal Search Parameters:

Included in this release are internal search parameters used to limit search scope to a particular library or collection. These are not included in the OpenURL specifications and should be considered extensions. They include:

rft.provider_uid
rft.collection_uid
rft.content
rft.institution_id 

Resolving multiple queries at the same time

A JSON only version of multiple OpenURLs in one request/response is now available. Using the new openurl/mresolve address a JSON formatted set of queries can be sent with a single request. A single response will be returned containing the results for all of the different queries. Using this version of the API allows a client to cut down on the HTTP traffic between their system and the KB API when issuing many queries at once. To send multiple queries, they need to be serialized into a json object. Ex:

{"q1":{"rft_id":"info:pmid/17014720"},"q2":{"rft.issn":"0028-0836"}}

To use the mutiple resolve function please use mresolve instead of resolve as the method endpoint.

Examples

For the following example we will be using the OCLC Training & Testing symbol whose OCLC symbol is TRN and whose registry ID is 105357 (http://worldcat.org/registry/Institutions/105357). We will also be using a specific citation for an article titled, Nature's Choices, found in Nature, 2010 Feb 18; 463(7283): 850 (http://www.worldcat.org/title/natures-choices/oclc/588264763&referer=brief_results).

Using http://worldcat.org/webservices/kb/openurl/resolve as the API endpoint we can then craft the following request (line breaks inserted for readability):

http://worldcat.org/webservices/kb/openurl/resolve?
rft.title=Nature
&rft.issn=0028-0836
&rft.oclcnum=1586310
&rft.date=2010-02-18
&rft.volume=463
&rft.issue=7283
&rft.spage=850
&rft.atitle=Nature's+choices
&svc_id=json
&rft.content=fulltext
&rft.institution_id=105357
&rfr_id=info/sid:library.edu/DEMO
&wskey=TjBKm4f7QdZwx //NOT A VALID KEY

Journal/book level information:

In order for a search to succeed, at least one of these is required: 

As with all of the KB parameters, all information should be present if it is available. Based on the citation found in WorldCat.org, here are the values for the fields we will be sending:

Article level information:

Article level information is used to identify a specific article within the journal. Most fields are not used directly by the API, but may be used to formulate an article link to give to the user. 

Just as we did with the journal level information, we will put values into these field whenever they are present in the citation: 

WorldCat Knowledge Base API specific commands/filters:

These are control fields that can be used to send additional information or filter commands to KB. They should be chosen based on the type of query being done.

For these fields, we must choose which make sense for the type of query we are doing.

WorldCat Knowledge Base API OpenURL Parameters: