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>. Some of our older records include the <nonSort> element, which holds initial articles, like "The" or "A."
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.
Date The date of creation or publication of the item content. An item may have zero or more <dateCreated> or <dateIssued> elements. Many of our dates are encoded in yyyy-mm-dd format, but some are still encoded in free text (ex., "ca. 1800"). Date ranges are represented by two date elements, 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".
Subject Subjects may be of type <topic>, <geographic>, <name>, <temporal>, or <titleInfo>. Complex subjects may include a combination of any of these subelements. For complex subjects (LCSH), subelements are usually displayed with "--" delimiters in the order they appear within the <subject> element.
Type of Resource The general type of the item's content. An item may have one or more of this element. Values will be one of: "text", "still image", "cartographic", "notated music", "sound recording", "sound recording-musical", "sound recording-nonmusical", "moving image", "three dimensional object", "mixed material".
Genre A more specific category of item content than type of resource. An item may have zero or more genres.

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

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