...
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.
| Anchor | ||||
|---|---|---|---|---|
|
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.
Yes| Name | On LC Solr field list? | Keyword Search | Exact Match Search | Can Sort | Can Facet | MODS Field Mapping | Notes | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
title | Y | Yes | Yes | No | No | titleInfo.title | https://api.lib.harvard.edu/v2/items?title=complete motown singles Case-sensitive exact match: | ||||||
name | Y | Yes | Yes? | No | Yes | name.namePart e.g. "Greenblatt, Stephen" | Will find term in any name field: ?Search by name_exact returns 0 for known items: | ||||||
role | Y | Yes | Yes? | Yes** | 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 | Yes | Yes? | Yes** | 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 | Y | No | Yes? | No | Yes | typeOfResource.collection Indicates whether or not a record describes a collection of items. | https://api.lib.harvard.edu/v2/items?q=colonial+north+america&isCollection=true | ||||||
isManuscript | Y | No | Yes? | No | Yes | typeOfResource.manuscript Indicates whether or not a record describes manuscript or archival material. | https://api.lib.harvard.edu/v2/items?q=colonial+north+america&isManuscript=true | ||||||
genre | Y | Yes | Yes | Yes** | Yes | genre | https://api.lib.harvard.edu/v2/items?q=fish+watercolor&genre=Drawings Case-sensitive exact match: | ||||||
originPlace | Y | Yes | Yes | No | Yes | originInfo.place | https://api.lib.harvard.edu/v2/items?q=colonial+north+america&originPlace=Boston Case-sensitive exact match: | ||||||
publisher | Y | Yes | Yes | No | Yes | originInfo.publisher | https://api.lib.harvard.edu/v2/items?q=shakespeare&publisher=Arden Case-sensitive exact match: | ||||||
originDate | Y | Yes | Yes | No | Yes | originInfo.dateIssued | https://api.lib.harvard.edu/v2/items?name=asimov+isaac&originDate=1961 Case-sensitive exact match: | ||||||
dateIssued | Y | Yes | future? | Yes | Yes | originInfo.dateIssued | https://api.lib.harvard.edu/v2/items?name=asimov%20isaac&dateIssued=1961 Case-sensitive exact match: | ||||||
dateCreated | Y | Yes | future? | Yes | Yes | originInfo.dateCreated | https://api.lib.harvard.edu/v2/items?q=daguerreotypes&dateCreated=1806 Case-sensitive exact match: | ||||||
dateCaptured | Y | Yes | future? | Yes | Yes | originInfo.dateCaptured | https://api.lib.harvard.edu/v2/items?dateCaptured=2016&genre=performed+music Case-sensitive exact match: | ||||||
copyrightDate | Y | Yes | future? | Yes | Yes | originInfo.copyrightDate | https://api.lib.harvard.edu/v2/items?copyrightDate=2010 Exact match seems to work, but not needed (copyrightDate is always 4 digit year) | ||||||
| dates.start | Y item api code does start/end processing | Yes | No | No | No | originInfo.dateIssued | This query returns all works by Molière published from 1990 forward: This query returns all works by Molière published from 1990 backward: This query returns all works by Molière published from 1990 to 2000: | ||||||
| dates.end | Yes | No | No | No | |||||||||
| dateRange | |||||||||||||
edition | Y | Yes | Yes | Yes | Yes | originInfo.edition | https://api.lib.harvard.edu/v2/items?name=Molière&edition=7th. ed. Case-sensitive exact match: | ||||||
issuance | Y | Yes | Yes | Yes | Yes | originInfo.issuance | This query returns items with subject "astronomy" issued as a serial: https://api.lib.harvard.edu/v2/items?subject=astronomy&issuance=serial | ||||||
languageCode | Y | No | Yes | No | Yes | language.languageTerm (where languageTerm type="code") | This query returns items of Shakespeare in Chinese: https://api.lib.harvard.edu/v2/items?name=shakespeare&languageCode=chi | ||||||
languageText | Y | Yes | Yes | No | Yes | language.languageTerm (where languageTerm type="text") facet as "language" rather than "languageText" | This query returns itemsby or about Laozi in Chinese: https://api.lib.harvard.edu/v2/items?title=laozi&language=Chinese | ||||||
physicalDescription | Y | No | No | physicalDescription.form | NOT WORKING (In mods2solr.xsl, in the mods:mods template, entry for physicalDescription field is commented out) https://api.lib.harvard.edu/v2/items?title=peanut&physicalDescription=print | ||||||||
abstractTOC | Y | Yes | No | No | No | abstract | This query returns items with the keyword "justinian" in an abstract or table of contents field: https://api.lib.harvard.edu/v2/items?abstractTOC=Justinian | ||||||
classification | Y | No | Yes | Yes |
| classification | https://api.lib.harvard.edu/v2/items?classification=F1435.3 Case-sensitive exact match: | ||||||
identifier (Identifier of an item in another system) | Y | No | Yes | Yes | No | identifier | This query returns an item by it's ISBN: | ||||||
| seriesTitle | Y item api code does the translation from seriesTitle | Yes | Yes? | No | Yes | In relatedItem[@type='series']: titleInfo.title facet as "relatedItem" rather than "seriesTitle" | https://api.lib.harvard.edu/v2/items?seriesTitle=Harvard-Yenching Institute Monograph Series | ||||||
subject | Y | Yes | Yes? | No | Yes? | subject.topic | https://api.lib.harvard.edu/v2/items?subject=perseus Case-sensitive exact match: ? subject_exact and facets=subject do not work for keywords located in subject.name OR subject.titleInfo | ||||||
subject.topic | Y | Yes | Yes | No | Yes | subject.topic | https://api.lib.harvard.edu/v2/items?subject.topic=Mochica pottery Case-sensitive exact match: | ||||||
subject.temporal | Y | Yes | Yes | No | Yes | subject.temporal | https://api.lib.harvard.edu/v2/items?q=samurai&subject.temporal=edo Case-sensitive exact match: | ||||||
| Y | Yes | Yes | No | Yes | subject.titleInfo.title | https://api.lib.harvard.edu/v2/items?subject.titleInfo=Middlemarch Case-sensitive exact match: | ||||||
subject.name | Y | Yes | Yes | No | Yes | subject.name | https://api.lib.harvard.edu/v2/items?subject.name=kubrick stanley Case-sensitive exact match: | ||||||
subject.name.role | Y | Yes? | Yes | No | Yes | subject.name.role.roleTerm | https://api.lib.harvard.edu/v2/items?subject.name.role=cmp ?Most role terms in this MODS path are terminated with a period (e.g. photographer.). Need to include punctuation or query will fail: OTOH, subject.genre also has terminal periods on terms but the solr query works with or without: | ||||||
subject.genre | Y | Yes | Yes? | No | Yes | subject.genre | https://api.lib.harvard.edu/v2/items?subject.genre=folklore ?Case-sensitive exact match DOESN"T WORK: | ||||||
subject.geographic | Y | Yes | Yes | No | Yes | subject.geographic | https://api.lib.harvard.edu/v2/items?subject.geographic=giza Case-sensitive exact match: | ||||||
subject.hierarchicalGeographic | Y | Yes? | Yes | No | No | subject.hierarchicalGeographic.continent | Solr query returns no results: ?But some of the individual MODS paths work in a query or as a facet, e.g.: | ||||||
subject.hierarchicalGeographic.continent | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.continent | NOT WORKING / Seems a valid SOLR field, but no values returned https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.continent=africa | ||||||
subject.hierarchicalGeographic.country | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.country | https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.country=canada | ||||||
subject.hierarchicalGeographic.province | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.province | NOT WORKING / Seems a valid SOLR field, but no values returned https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.province=quebec | ||||||
subject.hierarchicalGeographic.region | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.region | NOT WORKING / Seems a valid SOLR field, but no values returned https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.region=nile | ||||||
subject.hierarchicalGeographic.state | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.state | https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.state=massachusetts&q=maps | ||||||
subject.hierarchicalGeographic.territory | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.territory | NOT WORKING / Seems a valid SOLR field, but no values returned https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.territory=* | ||||||
subject.hierarchicalGeographic.county | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.county | https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.county=middlesex | ||||||
subject.hierarchicalGeographic.city | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.city | https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.city=Cochituate&q=maps | ||||||
subject.hierarchicalGeographic.island | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.island | NOT WORKING / Seems a valid SOLR field, but no values returned https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.island=* | ||||||
subject.hierarchicalGeographic.area | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.area | https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.area=galicia | ||||||
subject.hierarchicalGeographic.extraterrestrialArea | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.extraterrestrialArea | https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.extraterrestrialArea=* | ||||||
subject.hierarchicalGeographic.citySection | Y | Yes | Yes | No | Yes | subject.hierarchicalGeographic.citySection | https://api.lib.harvard.edu/v2/items?subject.hierarchicalGeographic.citySection=charlestown | ||||||
relatedItem | Yes | No | No | No | relatedItem.* Under revision 2018-05-23 | ||||||||
physicalLocation (Includes Harvard repository names but also non-Harvard locations) | Y | Yes | No | Yes |
| location.physicalLocation | https://api.lib.harvard.edu/v2/items?physicalLocation=tozzer&subject=cylinder seals | ||||||
repository (Includes Harvard repositories only) | N (item api code does the processing) | Yes | Yes | No | Yes | Search: location.physicalLocation (where @type="repository") Facet: extension.librarycloud.HarvardRepositories.HarvardRepository A search will query the long form repository name (e.g.Eda Kuhn Loeb Music Library); faceting will return the short form repository name (e.g. Loeb Music). | https://api.lib.harvard.edu/v2/items?q=peanuts&repository=Oakes Ames | ||||||
shelfLocator | Y | Yes | Yes | Yes | No | location.shelfLocator | https://api.lib.harvard.edu/v2/items?q=peanuts&shelfLocator=Film Mas Case-sensitive exact match: | ||||||
url | Y | No | Yes | No | No | location.url | https://api.lib.harvard.edu/v2/items?q=earhart amelia&url=*RAD.SCHL* Case-sensitive exact match: | ||||||
url.access | N (url.access.preview, url.access.raw_object are listed, but item api code uses url.access) | No | Yes | No | Yes | location.url.access (range = <preview, raw object, object in context>) Not working except for url.access=preview. facet as url.access.preview or url.access.raw_object | There's a typo in item api code: defined range values are "preview" and "raw object in context" but should be "preview", "raw object", and "object in context". "preview" value works, e.g.: https://api.lib.harvard.edu/v2/items?q=earhart amelia&url.access=preview "raw object in context" works as a query but it returns items without url@access="raw object", e.g.: https://api.lib.harvard.edu/v2/items?q=earhart%20amelia&url.access=raw object in context | ||||||
isOnline (Indicates whether or not an item is available in digital form; values are "true" or "false) | Y | No | No | Yes | Yes |
"true" if location.url[@access = 'raw object'] exists, "false" otherwise | https://api.lib.harvard.edu/v2/items?q=earhart amelia&isOnline=true | ||||||
source | Y | No | No | Yes | Yes | recordInfo.recordIdentifier source attribute Sources are currently MH:ALMA (from Alma), MH:VIA (image items from JSTOR forum), or MH:OASIS (finding aid components from ArchivesSpace). Attribute occurs only on top-level recordInfo.recordIdentifier elements | https://api.lib.harvard.edu/v2/items?q=earhart amelia&source=MH:ALMA | ||||||
recordIdentifier | Y | 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 be searched as keywords.) | https://api.lib.harvard.edu/v2/items?recordIdentifier=990148733450203941 (for Alma) https://api.lib.harvard.edu/v2/items?recordIdentifier=014873345 (for Aleph) https://api.lib.harvard.edu/v2/items?recordIdentifier=sch00227c00197 (for finding aids) https://api.lib.harvard.edu/v2/items?recordIdentifier=W42143_urn-3:FHCL:1176307 (for images) Use a keyword query to retrieve items based on record ID in finding aid components and image records: | ||||||
urn (?Queries an item by its NRS URN (the URN only e.g., " urn-3:FHCL:1155043" minus the actionable URL components) | Y | Yes | No | No | No | location.url | https://api.lib.harvard.edu/v2/items?urn=urn-3:FHCL:1155043 | ||||||
collectionTitle (Query by the set/collection title assigned to items that have been grouped together for delivery via Harvard Digital Collections) | Y | Yes | Yes | Yes | Yes | extension.sets.setName | https://api.lib.harvard.edu/v2/items?collectionTitle=Chinese Rare Books Case-sensitive exact match:https://api.lib.harvard.edu/v2/items?collectionTitle_exact=Chinese Rare Books | ||||||
collectionId (Query by the set/collection ID assigned to items that have been grouped together fo rdelivery via Harvard Digital Collections) | Y | No | Yes | No | Yes | extension.sets.systemId | https://api.lib.harvard.edu/v2/items?collectionId=84560 Case-sensitive exact match: | ||||||
| DRS Extensions | |||||||||||||
inDRS (Query for items in Harvard Library's digital repository service) | Y | No | Yes | Yes | extension.HarvardDRS.inDRS (range = <"true", "false">) | https://api.lib.harvard.edu/v2/items?genre=daguerreotype&inDRS=true | |||||||
See also: LibraryCloud Item API to query human-readable version of DRS accessFlags. | Y | No | Yes | Yes | extension.HarvardDRS.accessFlag (range = <P, R, N, B>) P (publicly accessible), R (restricted to Harvard), N (not available for delivery), B (bypass, access handled differently) | https://api.lib.harvard.edu/v2/items?genre=daguerreotype&accessFlag=P | |||||||
See also: LibraryCloud Item API to query by human-readable value derived from the contentModel for an object in Harvard's Digital Repository Service (DRS). | Y | Yes | Yes | Yes | extension.HarvardDRS.contentModel (range = <AUDIO, DOCUMENT, PDS DOCUMENT, PDS DOCUMENT LIST, STILL IMAGE, TEXT, VIDEO>) Use _exact query to find "DOCUMENT" | https://api.lib.harvard.edu/v2/items?title=biodiversity&limit=100&contentModel=PDS DOCUMENT Case-sensitive exact match: | |||||||
uriType (valid if inDRS=true) (Query for items by type of delivery urn, which is a proxy for type of delivery service) | Y | No | Yes | Yes | extension.HarvardDRS.uriType (range = <FDS, IDS, PDS, PDS_LIST, SDS, SDS_VIDEO>) Delivery service types: FDS (text documents), IDS (images), PDS (page-turned objects), PDS_LIST (list of page-turned objects), SDS (streaming audio), (SDS_VIDEO (streaming video) | https://api.lib.harvard.edu/v2/items?subject=jazz&uriType=SDS | |||||||
fileDeliveryURL (valid if inDRS=true) (Query an item by its full delivery URL) | Y | No | Yes | No | extension.HarvardDRS.fileDeliveryURL, eg. "http://nrs.harvard.edu/urn-3:FHCL.HOUGH:1090399" | https://api.lib.harvard.edu/v2/items?title=annual+report&fileDeliveryURL=https://nrs.harvard.edu/urn-3:HMS.COUNT:22923642 | |||||||
| ownerCode (valid if inDRS=true) | Y | No | Yes | Yes | extension.HarvardDRS.ownerCode, eg. "FHCL.HOUGH" | https://api.lib.harvard.edu/v2/items?q=cookbook*&ownerCode=RAD.SCHL | |||||||
| ownerCodeDisplayName (valid if inDRS=true) | Y | No | Yes | Yes | extension.HarvardDRS.ownerCodeDisplayName, eg. "Houghton Library" | https://api.lib.harvard.edu/v2/items?q=daguerreotype&ownerCodeDisplayName=Schlesinger | |||||||
metsLabel (valid if inDRS=true) (Query for items by keywords in the descriptive METS label - if defined in DRS metadata) | Y | Yes | Yes | No | extension.HarvardDRS.metsLabel eg. Any text string | https://api.lib.harvard.edu/v2/items?metsLabel=seward Case-sensitive exact match: | |||||||
lastModifiedDate (valid if inDRS=true) NOT WORKING | Y | No | Yes | No | extension.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. | 4/9/19 JW: item api reports "lastModifiedDate" as invalid field; note that field list, mods2solr.xsl and api code all refer to the field "_lastModifiedDate" but api reports this as undefined field also. https://api.lib.harvard.edu/v2/items?title_exact=Peanuts&lastModifiedDate=2015-08-21T21:16:36.389Z | |||||||
| maxImageDeliveryDimension | No | Future | No | Future | extension.HarvardDRS.maxImageDeliveryDimension - e.g., "600". Value is in pixels. | ||||||||
| LibraryCloud Extensions | |||||||||||||
See also: availableTo to query by DRS accessFlag.
| Y | No | Yes | No | Yes | extension.librarycloud.availableTo 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). | https://api.lib.harvard.edu/v2/items?q=colonialism&availableTo=Everyone | ||||||
See also: LibraryCloud Item API to query by the DRS content model of an object in Harvard's Digital Repository Service (DRS). | Y | 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. | https://api.lib.harvard.edu/v2/items?subject=poetry&digitalFormat=audio | ||||||||
processed.after | N | No | Yes | extension.librarycloud.processingDate Use YYYY-MM-DD format to search. | These date queries work, but # of matching hits is very high. What is meaning/context of processed.after and processed.before? This query returns items processed after the date specified: This query returns items processed before the date specified: This query returns items processed between the specified dates: | ||||||||
processed.before | |||||||||||||
| Sets Extensions | |||||||||||||
| setName | Y | Yes | No | Yes | extension.sets.set.setName Human-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. | https://api.lib.harvard.edu/v2/items?setName=chinese rare books | |||||||
| setSpec | Y | Yes | No | Yes | extension.sets.set.setSpec Codes used to identify a set of materials selected by, for example, a curator for administrative or discovery purposes or for harvesting via OAI-PMH. | https://api.lib.harvard.edu/v2/items?setSpec=crb |
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
...