Library Locations

Geographic proximity sort

Requests for library location information returns information about the libraries that indicate they hold the item. The library location information is sorted by geographic proximity. 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.

Currently the location parameter of country is the only option that provides geographic coverage for less commonly used locations. For all other sort options the area’s currently able to sort by geographic area are Australia, Canada, France, Germany, Great Britain, the Netherlands, South Africa, and the United States. For libraries in countries other than those listed, the IP address or lat/long parameter will provide news of the closest locations within the listed countries, before giving locations in other countries. So, for all other countries, use the location parameter requesting that country by name or ISO code. If you intend to use the API within an area that is not currently covered for more precise handling, please fill out the WorldCat Search API contact form so that the needed information can be installed for the new geographic area.

Location parameter

The parameter fits the pattern of ?location=[postal code|state,province,country name or code]. 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 and sort the results to that location. Currently all countries are available for this type of sort by name or ISO country code. The states and provinces of Canada and the United States are also available.

IP address parameter

The parameter fits the pattern of ?ip=[ip address number]. 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 no location, lat/long, or IP address parameter is sent, then the default location is the IP address of the requesting server.

Latitude & Longitude parameter

The parameter fits the pattern of ?lat=[latitude number]&lon=[longitude number]. 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.

Library type parameter

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.

Identifying libraries in an area

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.

Navigation

You can navigate through sets of library locations using the startLibrary and maximumLibraries parameters. The default is to start at the first/closest library and to present 10 libraries. The maximum libraries possible with a single query are 100 libraries.

The request pattern for different record identifiers
(here shown with ?location instead of the lat/long or ip parameter) :

for an OCLC number:
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]&format=[json]&callback=[callback]
or, for an ISBN:
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]&format=[json]&callback=[callback]
or, for an ISSN:
http://www.worldcat.org/webservices/catalog/content/libraries/issn/[issn]?location=[postal code|state,province,country name or code]&startLibrary=[number]&maximumLibraries=[number]&libtype=[n]&wskey=[key]&format=[json]&callback=[callback]

or for a standard number
http://www.worldcat.org/webservices/catalog/content/libraries/sn/[standard number]?location=[postal code|state,province,country name or code]&startLibrary=[number]&maximumLibraries=[number]&libtype=[n]&wskey=[key]&format=[json]&callback=[callback]

or, without a record identifier (*see note):
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]&format=[json]&callback=[callback]

*Note: when no record identifier is given the result is to provide the nearest libraries to that location that has provided holdings information in WorldCat.

JSON

The format parameter and callback parameter are only used with the JSON output format.

Standard number

The standard number value includes all standard numbers except the OCLC number. The standard number does include ISBNs, ISSNs, LCCNs, Universal Product Code, and just about any other standard number used represent items. For all of these identifiers, all punctuation is removed, except the ISSN and ISBN can include hyphens.

The exception to the standard number value rules is with the Library of Congress control number (LCCN). The 010 value was only indexed and then only as single words. So, if a standard number request is using an LCCN, the number is available with the year and then six digit serial number with leading zeros for any unused digits. The years before 2001 were included as two digits, while the years 2001- use four digits. For prefixes up to 2000, any prefixes less than three characters are not included, but three digit characters are included. For prefixes included for years 2001 on, a single character is not included but two character prefixes are included. So for example, the LCCN sn92-1234 is included as 92001234 only, and an LCCN of map92-1234 is retrieved as map92001234 only. (No suffix or revision dates are included.) And while n2009-123 is retrieved as 2009000123, the LCCN no2009-12 is retrieved by no2009000012. More information on LCCN numbers is found here - http://www.loc.gov/marc/lccn_structure.html.

Please be sure to also consider the impact of FRBR Grouping and Service Level when determining the meaning and impact on the results.

FRBR Grouping

Note: the default option is to include all the library locations for any record that represents an edition of the item identified.  This is sometimes referred to as a "FRBRized" holdings results. To see holdings associated with only a single record, include the parameter frbrGrouping=off.  However, the “off” option only works with an OCLC number. 

Service Level

Note: the type of libraries retrieved will be impacted by what Service Level is used. 

• If no service level is given the libraries that are visible in WorldCat.org will be provided at the default level. This level can be used for any users without the user being authenticated as a library user.
• If the library information will be used only by authenticated users [library staff, patrons, faculty, students, and people within the library building] then the full service level can be used for more bibliographic data fields.

Some examples

Near the location associated with the IP address of the connecting client application:
http://www.worldcat.org/webservices/catalog/content/libraries/15550774?wskey=[key]&format=[json]&callback=[callback]

Near the zip code 94002:
http://www.worldcat.org/webservices/catalog/content/libraries/15550774?location=94002&wskey=[key]&format=[json]&callback=[callback]

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

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

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

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

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:
http://www.worldcat.org/webservices/catalog/content/libraries/15550774?ip=153.40.170.1&location=10029&wskey=[key]&format=[json]&callback=[callback]

The resulting library location information can be displayed in two possible formats

• XML
• JSON

OCLC symbol look up

Note: it is possible to just check to see if specific library symbols hold an item.  This function is called the Library Catalog URL for a record.