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.

http://api.lib.harvard.edu/v2/items.json?q=Schulz OR peanuts
The response will include all records where any field contains the text “Schulz” OR “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. There is currently no equivalent syntax to express "OR" or "NOT" with fielded query terms.

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.

Accented Characters and Punctuation

If your query terms contain accented characters, include these in the search:

https://api.lib.harvard.edu/v2/items?name=Saint-Exupéry, Antoine de
https://api.lib.harvard.edu/v2/items?name=Molière

If your query includes an ampersand, the ampersand must be replaced by the URL-encoded equivalent (%26). For example, to search the title Saxo Grammaticus & the life of Hamlet:

https://api.lib.harvard.edu/v2/items?title_exact=Saxo+Grammaticus+%26+the+life+of+Hamlet 

For searches that include other punctuation marks, if the search fails using the punctuation, try the search again without it.

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.

NameIn LC Solr indexKeyword SearchExact Match SearchCan SortCan FacetMODS Field MappingNotes

title

Y (title_keyword; type=text_en)

Yes

Yes

No*

No

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

*When multiple fields are involved, must define index field for sorting

https://api.lib.harvard.edu/v2/items?title=peanuts

title_exactY (title; type=string)YY (no)N NtitleInfo.title
titleInfo.subTitle
titleInfo.partNumber
titleInfo.partName
Case-sensitive exact match

https://api.lib.harvard.edu/v2/items?title_exact=Labour Party

name

 Y (name_keyword; type=text_en)

Yes

Yes*

No

Yes

name.namePart

e.g. "Greenblatt, Stephen"

Will find term in any name field.

https://api.lib.harvard.edu/v2/items?name=shakespeare
name_exact Y (name; type=string) Y (no)N name.namePart*Search by name_exact returns 0 for known items:
https://api.lib.harvard.edu/v2/items?name_exact=MacNeil

role

 Y (role_keyword; type=text_en)

Yes

Yes (no)

Yes (no)*

Yes

name.namePart.role.roleTerm

 https://api.lib.harvard.edu/v2/items?name=shakespeare&role=publisher

*Can't be sortable; there are multiple roleTerms in some records

resourceType

  Y (role_keyword; type=text_en)

Yes

Yes

Yes (no)*

Yes

typeOfResource

https://api.lib.harvard.edu/v2/items?name=shakespeare&resourceType=three dimensional object

 *get sorting error = can not sort on multivalued field

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

Y (isCollection; type=string)

No

Yes

No

Yes

typeOfResource.collection

https://api.lib.harvard.edu/v2/items?q=colonial+north+america&isCollection=true

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

Y (isManuscript; type=string)

No

Yes

No

Yes

typeOfResource.manuscript

https://api.lib.harvard.edu/v2/items?q=colonial+north+america&isManuscript=true

genre

Y (genre_keyword; type=text_en)

Yes

Yes

Yes (no)

Yes

genre

https://api.lib.harvard.edu/v2/items?q=fish+watercolor&genre=Drawings

originPlace

Y (originPlace_keyword; type=text_en)

Yes

No

No

Yes

originInfo.place
originInfo.place.placeTerm

https://api.lib.harvard.edu/v2/items?q=colonial+north+america&originPlace=Boston

publisher

Y (publisher_keyword; type=text_en)

Yes

Yes

Yes (no)

Yes

originInfo.publisher

https://api.lib.harvard.edu/v2/items?q=shakespeare&publisher=Arden

publisher_exactY (publisher; type=string)YYNYoriginInfo.publisher_exact works in this case:
https://api.lib.harvard.edu/v2/items?q=shakespeare&publisher_exact=Palgrave+Macmillan

originDate

Y (originDate_keyword; type=text_en)

Yes

Yes (no)

No (no)

Yes

originInfo.dateIssued

originInfo.dateCreated
originInfo.dateCaptured
originInfo.copyrightDate

originInfo.dateOther

https://api.lib.harvard.edu/v2/items?name=asimov+isaac&originDate=1961

dateIssued

Y (dateIssued_keyword; type=text_en)

Yes

future

Yes (No)

Yes

originInfo.dateIssued

https://api.lib.harvard.edu/v2/items?name=asimov%20isaac&dateIssued=1961

dateCreated

Y (dateCreated_keyword; type=text_en)

Yes

future

Yes (no)

Yes

originInfo.dateCreated

https://api.lib.harvard.edu/v2/items?q=daguerreotypes&dateCreated=1806

dateCaptured

Y (dateCaptured_keyword; type=text_en)

Yes

future

Yes (no)

Yes

originInfo.dateCaptured

https://api.lib.harvard.edu/v2/items?dateCaptured=2016&genre=performed+music

copyrightDate

Y (copyrightDate_keyword; type=text_en)

Yes

future

Yes (no)

Yes

originInfo.copyrightDate

https://api.lib.harvard.edu/v2/items?copyrightDate=2010
dates.startY (dateRange; type=date_range) – item api code does start/end processingYesNoNoNo

originInfo.dateIssued
originInfo.dateCreated

This query returns all works by Molière published from 1990 forward:
https://api.lib.harvard.edu/v2/items?name=Molière&dates.start=1990

This query returns all works by Molière published from 1990 backward:
https://api.lib.harvard.edu/v2/items?name=Molière&dates.end=1990

This query returns all works by Molière published from 1990 to 2000:
https://api.lib.harvard.edu/v2/items?name=Molière&dates.start=1990&dates.end=2000

dates.endYesNoNoNo

edition

Y (edition_keyword; type=text_en)

Yes

Yes

Yes

Yes

originInfo.edition

https://api.lib.harvard.edu/v2/items?name=Molière&edition_exact=7th. ed.

issuance

 

Yes

Yes

Yes

Yes

originInfo.issuance

 

languageCode
(Searches based on language ISO code)

 

No

Yes

No

Yes

language.languageTerm (where languageTerm type="code")

 

languageText
(Searches based on language name text)

 

Yes

Yes

No

Yes

language.languageTerm (where languageTerm type="text")

facet as "language" rather than "languageText"

 

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

 
seriesTitle YesYes  

In relatedItem[@type='series']:

titleInfo.title

titleInfo.subtitle

titleInfo.partName

titleInfo.partNumber

 

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.* Under revision 2018-05-23

 

physicalLocation

 

Yes

No

Yes

No

location.physicalLocation

 
repository 

Yes

Yes

No

Yes

Search: location.physicalLocation (where @type="repository")

Facet: extension.librarycloud.HarvardRepositories.HarvardRepository

 

shelfLocator

 

Yes

Yes

Yes

No

location.shelfLocator

 

url

 

No

Yes

No

No

location.url

 

url.access

 

No

Yes

No

Yes

location.url.access (range = <preview, raw object, object in context>) Not working except for url.access=preview.

 

isOnline

(Values are “true” or “false”)

 

No

Yes

Yes

Yes

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

 

source

 

No

Yes

Yes

Yes

recordInfo.recordIdentifier source attribute

sources are currently MH:ALEPH, MH:VIA, or MH:OASIS. Coming soon MH:ALMA

attribute occurs only on top-level recordInfo.recordIdentifier elements

 

recordIdentifier

 

No

Yes

No

No

recordInfo.recordIdentifier at the top level only

priorrecordids.recordIdentifier

e.g. recordIdentifier=sch00443c00007  (for finding aids), recordIdentifier=S26791_olvsurrogate827653 (for images), recordIdentifier=012956251 (for Aleph)

(Internal recordInfo.recordIdentifier elements in finding aid components and image records can searched as keywords.)

 
urn YesNoNoNolocation.url 
collectionTitle
(see LibraryCloud Collections API)
 YesYesYesYesextension.collections.collection.title 
collectionId
(see LibraryCloud Collections API)
 NoYesNoYesextension.collections.collection.identifier 
DRS Extensions       
inDRS NoYes Yesextension.HarvardDRS.inDRS  (range = <"true", "false">) 
accessFlag (valid if inDRS=true) NoYes Yes

extension.HarvardDRS.accessFlag (range = <P, R, N, B>)

A new facet extension, "availableTo", in item records for only "Everyone" (corresponds to accessFlag=P) and "Harvard only" (corresponds to accessFlag=R).

 
contentModel (valid if inDRS=true) YesYes Yes

extension.HarvardDRS.contentModel (range = <AUDIO, DOCUMENT, PDS DOCUMENT, PDS DOCUMENT LIST, STILL IMAGE, TEXT, VIDEO>) Use quoted string to find "DOCUMENT"

 
uriType (valid if inDRS=true) NoYes Yes

extension.HarvardDRS.uriType  (range = <FDS, IDS, PDS, PDS_LIST, SDS, SDS_VIDEO>)

 
deliveryURL (valid if inDRS=true) NoYes Noextension.HarvardDRS.deliveryURL, eg. "http://nrs.harvard.edu/urn-3:FHCL.HOUGH:1090399"
 
ownerCode (valid if inDRS=true) NoYes Yesextension.HarvardDRS.ownerCode, eg. "FHCL.HOUGH"
 
ownerCodeDisplayName (valid if inDRS=true)    Noextension.HarvardDRS.ownerCodeDisplayName, eg. "Houghton Library"
 
 
metsLabel (valid if inDRS=true) YesYes Noextension.HarvardDRS.metsLabel  eg. Any text string
 
lastModifiedDate (valid if inDRS=true) NoYes Noextension.HarvardDRS.lastModifiedDate - eg. "2016-05-03T19:24:18.334Z". NOTE: This value needs to be converted into a searchable form, and the example value will change.

3/14/19 JW: Not working using short or long date; error=undefined field
https://api.lib.harvard.edu/v2/items?title_exact=Peanuts&lastModifiedDate=2015-08-21T21\:16\:36.389Z

https://api.lib.harvard.edu/v2/items?title_exact=Peanuts&lastModifiedDate=2015-08-21

maxImageDeliveryDimension NoFutureNoFutureextension.HarvardDRS.maxImageDeliveryDimension - e.g., "600". Value is in pixels. 
processed.after  Yes  mods:extension.processingDate:processingDate. Use YYYY-MM-DD format to search. 
LibraryCloud Extensions       
availableTo  Yes(?)NoYes

Human-readable values for access to digital content in Harvard's Digital Repository Service (DRS).

Values are "Everyone" (corresponds to accessFlag=P) and "Harvard only" (corresponds to accessFlag=R).

 
digitalFormat Yes  Yes

extension.librarycloud.digitalFormats.digitalFormat

Human readable values derived from the contentModel for an object in Harvard's Digital Repository Service (DRS).

Values are audio, books and documents, images, and video.

Sets Extensions       
setName Yes NoYesextension.sets.set.setNameHuman-readable names that identify a set of materials selected by, for example, a curator for administrative or discovery purposes or for harvesting via OAI-PMH.
setSpec Yes NoYesextension.sets.set.setSpecCodes used to identify a set of materials selected by, for example, a curator for administrative or discovery purposes or for harvesting via OAI-PMH.

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 a specific component identifier in VIA (the identifier actually has the form "<viaRecordId>_<URN>", but the wildcard matches the URN portion if not known.
http://api.lib.harvard.edu/v2/items?recordIdentifier=W188002*
 
#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" DRS Access Flag field not yet released to production API)
http://api.lib.harvard.edu/v2/items?title=peanuts&source=MH:VIA&accessFlag=P

#Get the facet counts for collections with various collection titles

https://api.lib.harvard.edu/v2/items?facets=collectionTitle

#Get all manuscripts from Schlesinger Library that contain either the string "electronic finding aid available" OR "electronic container list available"

https://api.lib.harvard.edu/v2/items?physicalLocation=sch&isManuscript=true&q=(https://api.lib.harvard.edu/v2/items?physicalLocation=sch&isManuscript=true&q=(electronic%20finding%20aid%20available)%20OR%20(electronic%20container%20list%20available))

Support

LibraryCloud Support



 

  • No labels