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.

The New York Public Library Digital Collections API

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

Sign Up and Authentication

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).

Sign Up

Sign In

Access Methods

There are two ways to access the API: via a browser, or via token authentication.

  1. Make a call to the API through the browser

    • Either provide you username and password when prompted by the browser:

      http://api.repo.nypl.org/api/v1/items/search?q=cats&publicDomainOnly=true
    • Or pass your username and password to the browser directly:

      http://username:password@api.repo.nypl.org/api/v1/items/search?q=cats&publicDomainOnly=true
  2. Make a call using a curl request or from a background application using the token

    In 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})
                    
    
                  

REST API version

The most recent version of the API is v1.

API Request Limitations

The limit per authentication token while connecting from an application or curl request is 10,000 requests per day.


Table of Contents

A note about our data model

Key concepts:

  • Collection
  • Container
  • Item
  • Capture

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.)

MODS help

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.

Parameters To Pass To The API

Available Request Parameters

Formats

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

Pagination

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

Public Domain Filtering

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

Rights statements in the Digital Collections API

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.

Available endpoints and how to use them

Method 1: Search across all MODS metadata fields

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

Method 2: Search in a particular MODS metadata field

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

Method 3: Return MODS Bibliographic Data Record for any UUID

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

Method 4: Return Captures for a UUID

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

Method 5: Return MODS Bibliographic Data Record and Capture Information for any UUID

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

Method 6: Return Captures Details and Related Capture Information for a Given Capture UUID

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

Method 7: Return All Collections

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

Method 8: Return All Children Captures for a Container or Collection UUID

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.

  • apiUri is a link to the child's MODS information
  • levelUri is a link to display hiearchical information below the child level.
  • grandParentLevelUri is a link to navigate to the parent of the current :uuid's record.

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

Method 9: Return Top-Level UUIDS

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

Method 10: Return UUID for local identifier

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

Examples of local identifier field names in MODS records:

          
            <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.

Method 11: Return recent additions

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

Method 12: Return Rights Profile for any UUID

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

Method 13: Return ALTO information as plain text for a capture UUID

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

Method 14: Return Minified ALTO information for a capture UUID

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

Method 15: Return METS ALTO information for a capture UUID

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

Method 16: Return subcollections for a collection or container UUID

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

Method 17: Return child items for a collection or container UUID

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