DEPRECATION NOTICE: Effective July 1st, 2022 Digital Collections API version 1.0 is deprecated to make way for a more usable and maintainable alternative in version 2.0. Please note that Digital Collections API version 1.0 will be removed permanently on January 3rd, 2023.
For more than a century, The New York Public Library has amassed an extraordinary trove of rare and unique material covering the full spectrum of recorded knowledge. Now, for the first time, significant portions of the Library's digitized collections are available as machine-readable data: over one million objects and records for you to search, crawl and compute. Sign up and get hacking today!
Questions/feedback? Write to: repoapi@nypl.org
You will need to authenticate in order to use the Digital Collections API -- either via direct login with a username/password, or an authentication token that you will receive when you sign up for API access. (See below for help with authentication).
There are two ways to access the API: via a browser, or via token authentication.
Either provide you username and password when prompted by the browser:
http://api.repo.nypl.org/api/v1/items/search?q=cats&publicDomainOnly=trueOr pass your username and password to the browser directly:
http://username:password@api.repo.nypl.org/api/v1/items/search?q=cats&publicDomainOnly=trueIn the examples below, 'abcdefghijklmn' is the authentication token you receive via email when you sign up for API access.
Example curl request:
curl "http://api.repo.nypl.org/api/v1/items/search?q=cats&publicDomainOnly=true" -H 'Authorization: Token token="abcdefghijklmn"'Example Ruby code:
url = "http://api.repo.nypl.org/api/v1/items/search?q=cats&publicDomainOnly=true"
uri = URI.parse(url)
http = Net::HTTP.new(uri.host, uri.port)
headers = { "Authorization" => "Token token=abcdefghijklmn" }
request = Net::HTTP::Get.new(uri.request_uri, headers)
response = http.request(request)
@response = response.body
Example Python code:
import requests
url = 'http://api.repo.nypl.org/api/v1/items/search?q=cats&publicDomainOnly=true'
auth = 'Token token=abcdefghijklmn'
call = requests.get(url, headers={'Authorization': auth})
The most recent version of the API is v1.
The limit per authentication token while connecting from an application or curl request is 10,000 requests per day.
Collections in Digital Collections are made up of one or more Items that are further organized by Containers.
A Collection may contain zero or more Containers, which can contain zero or more Containers and/or zero or more Items, creating a tree-like hierarchy (see below).
Not all Items belong to a Collection, but most do. (You can see the direct lineage
of an Item in the <relatedItem> fields of the /items/mods/[:uuid] response, Method #3 below.)
Items in Digital Collections are made up of one or more Captures that represent physical components, like the page of a book or the front of a photograph.
Each Capture has a corresponding image, video, or audio asset.
Example hierarchy:
| -- Collection
| -- Container
| -- Item
| -- Capture 1
| -- Capture 2
| -- Item
| -- Capture 1
| -- Capture 2
| -- Capture 3
| -- Container
| -- Item
| -- Capture 1
| -- Item
| -- Capture 1
| -- Container
| -- item
| -- Capture 1
| -- Capture 2
Etc.
(You can see a list of all Captures in an Item, Container, or
Collection, their basic information, and links to corresponding digital assets in the
/items/[UUID] response -- see Method #4 below.)
NYPL uses the MODS XML standard to describe the content of items in Digital Collections. You can view the schema documentation for element definitions, but here are some of the most commonly used elements:
| Element | Definition |
|---|---|
| Title | The title of the resource. An item may have one or more titles. The primary title of an item is denoted by
the <titleInfo> "usage" attribute with a value of "primary." A <titleInfo>
element might also contain other parts of the title, including <subtitle>, <partName>,
<partNumber>. |
| Type of Resource | The general type of the original resource content. Values are from an enumerated list and include: "text", "still image", "cartographic", "notated music", "sound recording", "moving image", "three dimensional object". |
| Identifier | An identifier associated with the resource. Locally, common identifiers are associated with source description, such as an NYPL catalog record or finding aid. |
| Date | The date of creation (<dateCreated>) or publication (<dateIssued>) of the resource.
Many of our dates are w3cdtf encoded in yyyy-mm-dd format, while some are represented as text strings (e.g., "ca. 2200 - 1600 BCE").
Date ranges are represented by two date subelements, each with a "point" attribute, one with the value "start" and one with "end".
Approximate or questionable dates are noted in the "qualifier" attribute with the value "approximate", "questionable", or "inferred". |
| Genre | Describes the nature of the content or function of the resource at a greater level of specificity than Type of Resource. |
| Physical Location | Specifies the NYPL content owner/division and physical location of the original resource. |
| Language | The language(s) expressed in a resource. |
| Name | A person or organization related to the creation or production of the item content. The role of the name can
be found in the <role> subelement. |
| Subject | Subjects may be of type <topic>, <geographic>,
<name>, <temporal>, <occupation>, or <titleInfo>.
Complex subjects may include a combination of any of these subelements. For complex Library of Congress Subject Headings,
subelements are usually displayed with "--" delimiters in the order they appear within the <subject> element. |
All API responses are available in json format and xml. The json is available by default, so .json can
be omitted; the XML can be accessed by appending .xml to the API call.
For example:
json:
xml:
| Parameter | Value | Default value | Optional | Description |
|---|---|---|---|---|
| .json | - | - | yes | return response in json format (default) |
| .xml | - | - | yes | return response in xml format |
If a response has many results, the request is paginated with the default results per page being 10. Users can get to the second page by passing in the page parameter, e.g. http://api.repo.nypl.org/api/v1/items/collection/5e66b3e8-e3dd-d471-e040-e00a180654d7.xml?page=2, or change the number of captures returned on a page with the per_page parameter http://api.repo.nypl.org/api/v1/items/collection/5e66b3e8-e3dd-d471-e040-e00a180654d7.xml?per_page=20. A combination of these two parameters also works http://api.repo.nypl.org/api/v1/items/collection/5e66b3e8-e3dd-d471-e040-e00a180654d7.xml?page=2&per_page=20.
| Parameter | Value | Default value | Optional | Description |
|---|---|---|---|---|
| per_page | integer, maximum 500 | 10 | yes | url parameter for number of rows to return per page |
| page | integer, starts at 1 | 1 | yes | returns current row of results |
The Public Domain filter limits results from the API to materials that have no copyright issues so you can easily work with the results and links to images without having to worry about potential US Copyright restrictions (see our Rights section of the Digital Collections about page for more info).
| Parameter | Value | Default value | Optional | Description |
|---|---|---|---|---|
| publicDomainOnly | Boolean: true, false | - | yes | returns only Public Domain results |
http://api.repo.nypl.org/api/v1/items/search?q=[search-terms]&publicDomainOnly=true
Example:
http://api.repo.nypl.org/api/v1/items/search?q=cats&publicDomainOnly=true
For certain materials that have been cleared as having no known U.S. Copyright restrictions, we are able to provide image links directly in the API responses.
For eligible materials, within the capture node in the item_details endpoint (See Method #6), there will be a imageLinks node, and within that, one or more
imageLink nodes. The imageLink node will feature the direct links to a variety of
derivatives.
The imageLinks, imageLink nodes also appear in all results using the Public Domain filter
described above.
The following are the possible derivative types you might find:
b - .jpeg center cropped thumbnail (100x100 pixels)
f - .jpeg (140 pixels tall with variable width)
t - .gif (150 pixels on the long side)
r - .jpeg (300 pixels on the long side)
w - .jpeg (760 pixels on the long side)
q - .jpeg (1600 pixels on the long side)
v - .jpeg (2560 pixels on the long side)
g - .jpeg original dimensions
Note: Not all captures will have all possible derivative types.
In the case of materials that have not explicitly been marked as "No Known U.S. Copyright restrictions," we're not
able to offer the direct links to the derivative types. For this reason, you may find an empty imageLinks
node. If you only want to work with the parts of the API that will have populated imageLinks, please see
the section above on "Public Domain Filtering."
For as many materials as possible, we also have included a highResLink node, which includes a link to
the original, uncropped 8-bit TIFF file (including color bars) that represents the original dimensions and uncompressed
image file that came off the camera in the NYPL Labs Digital Imaging Unit. These are enormous files, generally greater
than 200mb, so please be mindful when pulling these assets.
Note: In the case of materials that have not explicitly been marked as "No Known U.S. Copyright restrictions," we're
not able to offer the highResLink. If you only want to work with the parts of the API that will have
populated highResLink, please see the section above on "Public Domain
Filtering."
Rights statement apply to materials at the capture level, and generally describe the copyright status of those images to the extent that we have that status documented. Currently, there are four possible rights statements available via the Digital Collections API:
No Known U.S. Copyright:
We believe that this item has no known US copyright restrictions. The item may be subject to rights of privacy, rights of publicity and other restrictions. Though not required, if you want to credit us as the source, please use the following statement, "From The New York Public Library," and provide a link back to the item on our Digital Collections site. Doing so helps us track how our collection is used and helps justify freely releasing even more content in the future.
CC0:
To the extent that a jurisdiction grants The New York Public Library a copyright in this item, NYPL makes this item available under a Creative Commons CC0 1.0 Universal Public Domain Dedication: https://creativecommons.org/publicdomain/zero/1.0/ Though not required, if you want to credit us as the source, please use the following statement, "From The New York Public Library," and provide a link back to the item on our Digital Collections site. Doing so helps us track how our collection is used and helps justify freely releasing even more content in the future.
Copyright Held or Managed by the New York Public Library:
The New York Public Library holds or manages the copyright(s) in this item. If you need information about reusing this item, please go to http://nypl.org/permissions.
Undetermined:
The New York Public Library is interested in learning more about items you've seen on our websites or elsewhere online. If you have any more information about an item or its copyright status, we want to hear from you. Please contact DigitalCollections@nypl.org with your contact information and a link to the relevant content.
Description: This endpoint returns results that match a given keyword anywhere in a capture's MODS metadata record.
Request URL:
http://api.repo.nypl.org/api/v1/items/search[.:format]?q=[:search-terms]
Request Values: one or more search-terms
Return Values: imageID, itemLink, apiItemURL, apiItemDetailURL, uuid (capture), title (capture), search_text, page, perPage, totalPages, numResults
Example Request: http://api.repo.nypl.org/api/v1/items/search.xml?q=birds
Description: This endpoint returns results that match a given keyword anywhere in a particular MODS metadata field. Searchable MODS fields include these top level elements: identifier, typeOfResource, note. Searchable fields also include the following subelements: title, namePart, place, publisher, topic, geographic, temporal, genre, physicalLocation, and shelfLocator. For more information on MODS elements, see the "MODS help" section above.
Request URL:
http://api.repo.nypl.org/api/v1/items/search[.:format]?q=[:search-terms]&field=[:mods-field]
Request Value: one or more search terms, a valid MODS field
Return Values: imageID, itemLink, apiItemURL, apiItemDetailURL, uuid (capture), title (capture), search_type, search_text, page, perPage, totalPages, numResults
Example Request: http://api.repo.nypl.org/api/v1/items/search.xml?q=flying&field=topic
Description: This endpoint returns the MODS information for the requested ID.
Request URL: http://api.repo.nypl.org/api/v1/mods/[:id]
Request value: Users can pass in a capture, an item, or a container or a collection ID.
Return Values: A MODS bibliographic data record (See "MODS Help" section for list of possible data elements)
Example Request: http://api.repo.nypl.org/api/v1/mods/5e66b3e8-e3dd-d471-e040-e00a180654d7.xml
Description: Return all capture UUIDs, imageIDs, itemLinks and titles (optional) for any UUID
Request URL: http://api.repo.nypl.org/api/v1/items/[:uuid]
Request Value: a UUID for an item, a container, or a collection. Capture UUIDs are not valid input values.
Return Values: uuid (capture), imageID, itemLink, title (capture, optional), page, perPage, totalPages, numResults
Example Request: http://api.repo.nypl.org/api/v1/items/d5aa2f40-c53a-012f-9dac-58d385a7bc34.xml or http://api.repo.nypl.org/api/v1/items/d5aa2f40-c53a-012f-9dac-58d385a7bc34.xml?withTitles=yes
Description: This endpoint returns the MODS information and capture information for the requested ID.
Request URL: http://api.repo.nypl.org/api/v1/items/mods_captures/[:id]
Request value: Users can pass in a capture, an item, or a container or a collection ID. Page and per_page params optional.
Return Values: A MODS bibliographic data record (See "MODS Help" section for list of possible data elements); uuid (capture), imageID, itemLink, title (capture, optional), page, perPage, totalPages, numResults
Example Request: http://api.repo.nypl.org/api/v1/items/mods_captures/5e66b3e8-e3dd-d471-e040-e00a180654d7.xml
Description: This endpoint returns MODS for a capture along with information about related captures. The expected id here is a capture id.
Additional fields provide information about sibling captures (sibling_captures), captures related at the root collection level (root_captures), and immediate neighboring captures (imm_captures). sibling_captures will always contain at least one capture because the capture is listed as a sibling of itself. In the case of recto/verso (a scan of the front and back of a single piece of paper), there should be in total two sibling captures. In the case of a scanned book, there will be many sibling captures. Root captures will display all captures associated with the requested capture. Immediate captures (imm_captures) will display all captures in the parent container. This number will be the same as root_captures if the captures belong to a collection or container at the top of the hierarchy. Otherwise, immediate captures will only display everything "one level up."
Sibling captures will display metadata about each capture contained within the <capture> field.
The total number of captures is listed one level above as <numResults> after the
<mods> information. Alternatively, root_captures and imm_captures return the total number of
captures nested within the element, also as <numResults>. Following the closed
</numResults> tag, each capture is represented within the <capture> tags.
Request URL: http://api.repo.nypl.org/api/v1/items/item_details/[:id]
Request Value: Users can pass in only a capture ID.
Return Values: Each capture in this response contains the following fields: uuid, imageLinks, typeOfResource, imageID, sortString, itemLink.
Example Request: http://api.repo.nypl.org/api/v1/items/item_details/5e66b3e8-e3dd-d471-e040-e00a180654d7.xml
Request URL: http://api.repo.nypl.org/api/v1/collections
Description: Returns paginated information about all collections. Useful as a starting point for navigating down from the top of the hierarchy. Includes no item records without parents (orphan items, belonging to no collection).
Request Value: No URL parameters required.
Return Values: Top level collection information.
Example Request: http://api.repo.nypl.org/api/v1/collections.xml OR http://api.repo.nypl.org/api/v1/collections
Request URL: http://api.repo.nypl.org/api/v1/collections/[:uuid]
Description: Returns paginated information about all children for a given collection or subcollection's UUID. Useful for following information through the hierarchy.
Request Value: Collection or subcollection (container) uuid. Page and per_page params optional.
Return Values: Collection's children information, including links to continue to child MODS information or child hierarchy level.
I.e., use levelUri to go lower in the hierarchy, grandParentUri to go above where you are now, apiUri to learn more about the child.
Example Request: http://api.repo.nypl.org/api/v1/collections/d94adb20-c53a-012f-399c-58d385a7bc34.xml
Request URL: http://api.repo.nypl.org/api/v1/items/roots
Description: Returns all top-level UUIDS. These UUIDs can then be used to drill down to deeper content. Response is not paginated. Responds as either XML or JSON (default). Results returned are limited by rights restrictions.
Response returns both uuids for top-level collection records as well as item records without parents (orphan items, belonging to no collection).
Request Value: No URL parameters required.
Return Values: Top level UUIDs.
Example Request: http://api.repo.nypl.org/api/v1/items/roots.xml OR http://api.repo.nypl.org/api/v1/items/roots
Request URL: http://api.repo.nypl.org/api/v1/items/[:local_identifier-field-name]/[:local-identifier-value]
Description: Return uuid for a local identifier. Local_identifier field names can be found in the "type" attribute of the MODS <identifier> element (e.g. <identifier> type="local_[:identifier-field-name]">).
Request Value: a valid local identifier.
Return Values: uuid, page, perPage, totalPages, numResults.
Example Request: http://api.repo.nypl.org/api/v1/items/local_image_id/1666689 OR http://api.repo.nypl.org/api/v1/items/local_image_id/1666689.xml
<identifier displayLabel="RLIN/OCLC" type="local_other">40687640</identifier>
<identifier displayLabel="NYPL catalog ID (B-number)" type="local_bnumber">b13987862</identifier>
<identifier displayLabel="Hades struc ID (legacy)" type="local_hades">1067457</identifier>
<identifier displayLabel="Barcode" type="local_barcode">33333201354160</identifier>
Important Note: Capture-uuids are not returned in the response for this method. To find the associated capture uuid(s) for an item, call Method 1 (Return Captures for UUID) with the item-uuid value that is returned in this response.
Request URL:http://api.repo.nypl.org/api/v1/items/recent
Description: Returns paginated list of most recently added captures.
Request Value: No URL parameters required.
Return Values: uuid, apiUri, typeOfResource, imageID, sortString, dateDigitized, itemLink, title, rightsStatement, rightsStatementURI.
Example Request: http://api.repo.nypl.org/api/v1/items/recent.xml OR http://api.repo.nypl.org/api/v1/items/recent
Request URL:http://api.repo.nypl.org/api/v1/items/rights/[:uuid]
Description: Returns rights profile information for the given uuid.
Request Value:A valid capture uuid.
Return Values:useStatement, rightsNotes.
Example Request: http://api.repo.nypl.org/api/v1/items/rights/d9067de0-aa17-0133-ab91-60f81dd2b63c.xml OR http://api.repo.nypl.org/api/v1/items/rights/d9067de0-aa17-0133-ab91-60f81dd2b63c.xml
Request URL:http://api.repo.nypl.org/api/v1/items/plain_text/[:uuid]
Description: Returns an array of altos, with parsed plain text, for a given capture UUID.
Request Value:A valid capture uuid.
Return Values:alto, uuid, plainText, rightsStatement.
Example Request: http://api.repo.nypl.org/api/v1/items/plain_text/8fcbf960-fed9-0130-73f0-58d385a7bbd0.xml OR http://api.repo.nypl.org/api/v1/items/plain_text/8fcbf960-fed9-0130-73f0-58d385a7bbd0
Request URL:http://api.repo.nypl.org/api/v1/items/minified_alto/[:uuid]
Description: Returns an array of minified alto for a given capture UUID.
Request Value:A valid capture uuid.
Return Values:alto, uuid, minContent.
Example Request: http://api.repo.nypl.org/api/v1/items/minified_alto/8fcbf960-fed9-0130-73f0-58d385a7bbd0.xml OR http://api.repo.nypl.org/api/v1/items/minified_alto/8fcbf960-fed9-0130-73f0-58d385a7bbd0
Request URL:http://api.repo.nypl.org/api/v1/items/mets_alto/[:uuid]
Description: Returns an array of mets alto for a given capture UUID.
Request Value:A valid capture uuid.
Return Values:alto, Description, Styles, Layout.
Example Request: http://api.repo.nypl.org/api/v1/items/mets_alto/8fcbf960-fed9-0130-73f0-58d385a7bbd0.xml OR http://api.repo.nypl.org/api/v1/items/mets_alto/8fcbf960-fed9-0130-73f0-58d385a7bbd0
Request URL:http://api.repo.nypl.org/api/v1/collections/[:uuid]/subcollections
Description: Returns immediate child containers of collection or container with the supplied uuid. Does not return items or captures.
Request Value:A valid collection or container uuid.
Return Values:numSubCollections, numItems, numResults, collection.
Example Request: http://api.repo.nypl.org/api/v1/collections/17513b20-c52e-012f-78fb-58d385a7bc34/subcollections.xml OR http://api.repo.nypl.org/api/v1/collections/17513b20-c52e-012f-78fb-58d385a7bc34/subcollections
Request URL:http://api.repo.nypl.org/api/v1/collections/[:uuid]/items
Description: Returns items directly attached to container or items attached to, though not necessarily directly beneath, a collection.
Request Value:A valid collection or container uuid.
Return Values:numSubCollections, numItems, numResults, item array.
Example Request: http://api.repo.nypl.org/api/v1/collections/17e4bce0-c52e-012f-8d13-58d385a7bc34/items.xml OR http://api.repo.nypl.org/api/v1/collections/17e4bce0-c52e-012f-8d13-58d385a7bc34/items