Skip to end of metadata
Go to start of metadata

Overview

The LibraryCloud Item API provides access to metadata about items in the Harvard Library collections. For the purposes of this API, an “item” is the metadata describing a catalog record within the Harvard Library. LibraryCloud Item API searches over 20,000,000 aggregated metadata records. Records are sourced from ALEPH for over 13,500,000 open access bibliographic records, VIA for over 4,500,000 visual information components, and OASIS for almost 2,000,000 archival finding aid components

Base URI

http://api.lib.harvard.edu/v2/items

Simple Query

The simplest query to the API includes only a search term:
http://api.lib.harvard.edu/v2/items?q=peanuts
The response will include all records where any field contains the text “peanuts”, as XML

Multiple terms may be used in a simple query:
http://api.lib.harvard.edu/v2/items.json?q=Schulz+peanuts
The response will include all records where any field contains the text “Schulz” AND “peanuts”, as JSON.

Simple Response

The response to any query contains the total number of matching records, the number of records included within this response, the page number of this response, and the matching records. 

Sample XML Response:
http://api.lib.harvard.edu/v2/items?q=peanuts

Searching by Field

A query can be limited to a particular field:
http://api.lib.harvard.edu/v2/items?title=peanuts
This query returns all items with the text “peanuts” in the title field.

Query terms can be combined:
http://api.lib.harvard.edu/v2/items?title=peanuts&q=snack
This query returns all items with the text “peanuts” in the title field and “snack” anywhere in the record.

http://api.lib.harvard.edu/v2/items?title=peanuts&name=Schulz
This query returns all items with the text “peanuts” in the title field and “Shulz” in the name field.

Case-sensitive exact-match queries can be done on specific fields:
http://api.lib.harvard.edu/v2/items?title_exact=Peanuts
This query returns all items with a title of “Peanuts”.

See the Field Reference for a list of fields available for searching.

Stemming, Stopwords and Wildcards

LibraryCloud uses standard Solr index stemming and stopword lists. The stemming algorithm is based on the Porter stemming algorithm.

Keywords may be wild-carded with an asterisk:
http://api.lib.harvard.edu/v2/items?title=peanut*
http://api.lib.harvard.edu/v2/items?title=p*nut

Paging

By default, each response will include the first 10 records available. A query can request more records in a response (up to 250), and page through the results.
http://api.lib.harvard.edu/v2/items?title=peanuts?start=100&limit=50
Return the results for the query starting at item 100, with a page size of 50 (e.g. records 100 through 149).

ParameterDescription
start

The row number to start returning results from. If omitted, will default to 1.

limitThe number of results to return. Default is 10. May be between 0 and 250.

Sorting

Responses can sorted in ascending or descending order. See the Field Reference for a list of sortable fields.
http://api.lib.harvard.edu/v2/items?title=peanuts&sort.asc=resourceType
Sort results by the “resourceType” field, in ascending order.

ParameterDescription
sort.asc OR sort

The field to use for sorting, in ascending order

sort.descThe field to use for sorting, in descending order

Facets

Many fields are available for faceting (see the Field Reference for details).
http://api.lib.harvard.edu/v2/items.json?title=peanuts&facets=name,resourceType
Facet search results by the “name” and “resourceType” fields

ParameterDescription
facets

A comma-separated list of facets to return

facet_sizeThe maximum number of facets to be returned for each faceted field. Default is 10. May be between 1 and 100.

Response Format

By default, all responses are in MODS format. Dublin Core (DC) can be requested by adding .dc to the base URI
http://api.lib.harvard.edu/v2/items.dc?title=peanuts

Response Serialization

By default, all responses are returned as XML. Responses can be returned as JSON either by adding “.json” to the base URI, or by setting the “Accept” HTTP header in the request to “application/json”. When specifying both the response format and serialization, the format should be added first.
http://api.lib.harvard.edu/v2/items.json?title=peanuts
http://api.lib.harvard.edu/v2/items.dc.json?title=peanuts

Cross-domain queries

The API sets the necessary CORS header to allow cross-domain requests in supported browsers. Cross-domain queries can also use JSONP by specifying a callback function name in a “callback” parameter.
http://api.lib.harvard.edu/v2/items.json?title=peanuts&callback=myfunction

ParameterDescription
calback

Javascript function name. The response data will enclosed in a javascript function call with this name.

 

API Versioning

The version number of the API is specified in the base URL (e.g. “v2”). A version number is always required when accessing the API. The version number will be incremented whenever breaking (non backwards-compatible) changes are made to the API.

Field Reference

This section describes the fields available for searching through the API. In some cases, fields available through the API aggregate multiple fields with the MODS records. When applicable, this is identified in the MODS field mapping column.

NameKeyword SearchExact Match SearchCan SortCan FacetMODS Field Mapping

title

Yes

Yes

No

No

titleInfo.title
titleInfo.subTitle
titleInfo.partNumber
titleInfo.partName

name

Yes

Yes

Yes

Yes

name.namePart

e.g. "Greenblatt, Stephen"

role

Yes

Yes

Yes

Yes

name.namePart.role.roleTerm

resourceType

Yes

Yes

Yes

Yes

typeOfResource

isCollection
(Values are “true” or “false”)

No

Yes

No

Yes

typeOfResource.collection

isManuscript
(Values are “true” or “false”)

No

Yes

No

Yes

typeOfResource.manuscript

genre

Yes

Yes

Yes

Yes

genre

originPlace

Yes

No

No

Yes

originInfo.place
originInfo.place.placeTerm

publisher

Yes

Yes

Yes

Yes

originInfo.publisher

originDate

future

future

No

No

originInfo.dateIssued
originInfo.dateCreated
originInfo.dateCaptured
originInfo.copyrightDate

dateIssued

future

future

Yes

Yes

originInfo.dateIssued

dateCreated

future

future

Yes

Yes

originInfo.dateCreated

dateCaptured

future

future

Yes

Yes

originInfo.dateCaptured

copyrightDate

future

future

Yes

Yes

originInfo.copyrightDate

edition

Yes

Yes

Yes

Yes

originInfo.edition

issuance

Yes

Yes

Yes

Yes

originInfo.issuance

languageCode
(Searches based on language ISO code)

No

Yes

Yes

Yes

language.languageTerm

languageText
(Searches based on language name text)

future

future

future

future

language.languageTerm

physicalDescription

  

No

No

physicalDescription.form
physicalDescription.note

abstractTOC

Yes

No

No

No

abstract
tableOfContents

classification
(Physical organization code)

No

Yes

Yes

No

classification

identifier

No

Yes

Yes

No

identifier

subject

Yes

Yes

No

Yes

subject.topic
subject.geographic
subject.temporal
subject.titleInfo
subject.name
subject.genre
subject.hierarchicalGeographic.continent
subject.hierarchicalGeographic.country
subject.hierarchicalGeographic.province
subject.hierarchicalGeographic.region
subject.hierarchicalGeographic.state
subject.hierarchicalGeographic.territory
subject.hierarchicalGeographic.county
subject.hierarchicalGeographic.city
subject.hierarchicalGeographic.island
subject.hierarchicalGeographic.area
subject.hierarchicalGeographic.extraterrestrialArea
subject.hierarchicalGeographic.citySection

subject.topic

Yes

Yes

No

Yes

subject.topic

subject.temporal

Yes

Yes

No

Yes

subject.temporal

subject.title

Yes

Yes

No

Yes

subject.titleInfo.title
subject.titleInfo.subTitle
subject.titleInfo.partNumber
subject.titleInfo.partName

subject.name

Yes

Yes

No

Yes

subject.name
subject.name.namePart

subject.name.role

Yes

Yes

No

Yes

subject.name.role.roleTerm

subject.genre

Yes

Yes

No

Yes

subject.genre

subject.geographic

Yes

Yes

No

Yes

subject.geographic

subject.hierarchicalGeographic

Yes

Yes

  

subject.hierarchicalGeographic.continent
subject.hierarchicalGeographic.country
subject.hierarchicalGeographic.province
subject.hierarchicalGeographic.region
subject.hierarchicalGeographic.state
subject.hierarchicalGeographic.territory
subject.hierarchicalGeographic.county
subject.hierarchicalGeographic.city
subject.hierarchicalGeographic.island
subject.hierarchicalGeographic.area
subject.hierarchicalGeographic.extraterrestrialArea
subject.hierarchicalGeographic.citySection

subject.hierarchicalGeographic.continent

Yes

Yes

No

Yes

subject.hierarchicalGeographic.continent

subject.hierarchicalGeographic.country

Yes

Yes

No

Yes

subject.hierarchicalGeographic.country

subject.hierarchicalGeographic.province

Yes

Yes

No

Yes

subject.hierarchicalGeographic.province

subject.hierarchicalGeographic.region

Yes

Yes

No

Yes

subject.hierarchicalGeographic.region

subject.hierarchicalGeographic.state

Yes

Yes

No

Yes

subject.hierarchicalGeographic.state

subject.hierarchicalGeographic.territory

Yes

Yes

No

Yes

subject.hierarchicalGeographic.territory

subject.hierarchicalGeographic.county

Yes

Yes

No

Yes

subject.hierarchicalGeographic.county

subject.hierarchicalGeographic.city

Yes

Yes

No

Yes

subject.hierarchicalGeographic.city

subject.hierarchicalGeographic.island

Yes

Yes

No

Yes

subject.hierarchicalGeographic.island

subject.hierarchicalGeographic.area

Yes

Yes

No

Yes

subject.hierarchicalGeographic.area

subject.hierarchicalGeographic.extraterrestrialArea

Yes

Yes

No

Yes

subject.hierarchicalGeographic.extraterrestrialArea

subject.hierarchicalGeographic.citySection

Yes

Yes

No

Yes

subject.hierarchicalGeographic.citySection

relatedItem

Yes

No

No

No

relatedItem.name.namePart (if relatedItem.type == “series”)

physicalLocation

Yes

No

Yes

No

location.physicalLocation

shelfLocator (PENDING NEW RELEASE)

Yes

Yes

Yes

No

location.shelfLocator

url

No

Yes

No

No

location.url

url.access

No

Yes

No

Yes

location.url.access

isOnline

No

Yes

Yes

Yes

“true” if mods.url exists, “false” otherwise

source

No

Yes

Yes

Yes

recordInfo.recordContentSource

sources are currently MH:ALEPH, MH:VIA, or MH:OASIS

recordIdentifier

No

Yes

No

No

recordInfo.recordIdentifier

urnYesNoNoNolocation.url
collectionTitle
(see LibraryCloud Collections API)
YesYesYesYesextension.collections.collection.title
collectionId
(see LibraryCloud Collections API)
NoYesNoYesextension.collections.collection.identifier

Examples

#search all of LibraryCloud for “peanuts” in the title
http://api.lib.harvard.edu/v2/items?title=peanuts
 
#search oasis components for “peanuts” in the title
http://api.lib.harvard.edu/v2/items?title=peanuts&source=MH:OASIS   (can use MH:OASIS, MH:VIA, or MH:ALEPH)
 
#search for a specific component identifier in OASIS
http://api.lib.harvard.edu/v2/items?recordIdentifier=sch00443c00007&source=MH:OASIS
 
#search for all components in an OASIS record
http://api.lib.harvard.edu/v2/items?recordIdentifier=sch00443*

#look up the MODS for a PDS object given its URN

http://api.lib.harvard.edu/v2/items?urn=urn-3:FHCL.HOUGH:25620083

#search all of library cloud for VIA records that are public and have “peanuts” in the title  (NOTE: "restricted" field not yet released to production API)
http://api.lib.harvard.edu/v2/items?title=peanuts&source=MH:VIA&restricted=false

Support

LibraryCloud Support



 

  • No labels