The API

Getting Started

The Cooper Hewitt APIAPI (Computer Science) Application Programming Interface – a facility to allow a computer or application to access the data and/or functionality of another computer system or application gives you quick access to the data of 215,000 items in our collectionCollection (Museology) Museums are distinguished by their collection of unique objects that form the core of their activities for exhibitions, education, and research., along with information about the people, companies and other organizations that were associated with them.

The API uses GraphQLGraphQL (Computer Science) GraphQL is an open-source data query and manipulation language for APIs to access the data. To get started, connect via GraphQL to this endpoint:

https://api.cooperhewitt.org/

Start making queries

The API will support any GraphQL compatible client, including the command line or graphical user interfaces (GUIs) such as GraphiQLGraphiQL GraphiQL (note the "i" in the word) is an open source graphical interface used to query GraphQL APIs. You can use GraphiQL in our Try It Out section.. This site has embedded GraphiQL, so you can make GraphQL queries without any prior setup.

Incorporate the API in your code

When you want to incorporate queries into your own code, there are many tools available in a wide range of programming languages. Visit the GraphQL site to explore the options available.

Open access

The Cooper Hewitt API is open access, you do not have to register in order to use it. However, to prevent the overloading of the server, calls to the API will be rate limited by default. To remove this limit, you can apply for your own access key.

GraphQL

There are many styles and formats for applicationApplication (Computer Science) A computer software unit that provides functionality for particular use programming interfaces (APIs). The Cooper Hewitt APIAPI (Computer Science) Application Programming Interface – a facility to allow a computer or application to access the data and/or functionality of another computer system or application uses GraphQLGraphQL (Computer Science) GraphQL is an open-source data query and manipulation language for APIs, a flexible, fast and powerful “queryQuery (Computer Science) A query is a request for data or information from a database table or combination of tables, or an API that manages access to those tables language” used to define and work with APIs. You can find out more about GraphQL on their foundation’s website.

GraphQL queries follow this basic structure:

{
  objectObject (Museology) Artefact or specimen held in a museum collection.

(Computer science) A software "bundle" consisting of a set of variables which define the states the object can exist in and a set of functions that define its behavior. (argumentsArguments (Computer Science) Individual elements of information contained within a query, often structured as name / value pairs, e.g. title="chair") {
    fieldsFields (Computer Science) The smallest container of information in a database. A field is named, e.g. "Title" or "Date" and each record contains a group of fields.
  }
}

Once the query is sent to the API endpoint, the data that is returned follows the same structure as the query:

{
  “data”: {
    “object”: {
      “field”: valueValue (Computer Science) The representation given to the corresponding entity, often the public description of the entity.
    }
  }
}

Anatomy of a Record

The JSONJSON (Computer Science) JSON (JavaScript Object Notation) is a structured format for data that is lightweight (does not contain a lot of markup) and easy to parse. below shows a typical GraphQLGraphQL (Computer Science) GraphQL is an open-source data query and manipulation language for APIs responseResult (Computer Science) The data (in JSON format) that is returned by the API following a query. It will either contain records, or, if there is a problem with the query, an error message. from a queryQuery (Computer Science) A query is a request for data or information from a database table or combination of tables, or an API that manages access to those tables for a single objectObject (Museology) Artefact or specimen held in a museum collection. (Computer science) A software "bundle" consisting of a set of variables which define the states the object can exist in and a set of functions that define its behavior., in this case the Videosphere portable television.

{
  "data": {
    "object": [
      {
        "titleTitle (Museology) The name given to the design or work of art.": [
          {
            "type": "Descriptive title",
            "valueValue (Computer Science) The representation given to the corresponding entity, often the public description of the entity.": "Videosphere Model 3240 Portable Television"
          },
          {
            "type": "Model number",
            "value": "3240"
          },
          {
            "type": "Series/book title",
            "value": "Videosphere"
          }
        ],
        "summary": {
          "title": "Videosphere Model 3240 Portable Television"
        },
        "identifierIdentifier (API) A group of fields containing different unique identifiers for an object, agent, exhibition, or other unique datatype": [
          {
            "value": "2018-22-51",
            "type": "accession numberAccession Number (Museology) When an object is accessioned it receives a unique identifier called an Accession Number. These numbers may codify the year the object was accessioned, the department, or if the object is part of a series of objects that form a whole"
          },
          {
            "value": "285978",
            "type": "tms id"
          }
        ],
        "classificationClassification (API)  A formal terminology that can be applied to any object. Objects can have more than one classification.": [
          {
            "datatypeDatatype (Computer Science) A particular kind of data item, as defined by the values it can take, the programming language used, or the operations that can be performed on it. Predefined formats for data contained within fields, for example “number”, “string” (text) or “date”": {
              "base": "classification"
            },
            "id": "classification-204",
            "summary": {
              "title": "appliances & tools"
            }
          }
        ],
        "dateDate (Museology) The date range of the creation of the object. This value will have  'from', and 'to' key value pairs.": [
          {
            "from": "1970",
            "to": "1970",
            "value": "1970"
          }
        ],
        "departmentDepartment (API) The section of the museum that an object is associated with.": [
          {
            "collectionsOnlineIdcollectionsOnlineId (API) A legacy ID specific to Cooper Hewitt's collection site established in 2012": "35347475",
            "datatype": {
              "base": "department"
            },
            "id": "department-1",
            "identifier": [
              {
                "type": "tms id",
                "value": "1"
              }
            ],
            "summary": {
              "title": "Product Design and Decorative Arts Department"
            }
          }
        ],
        "descriptionDescription (API) Long-form, curatorial,  interpretive text created for context and additional descriptive elements.": [
          {
            "type": "digital table textDigital table text (API) Description to be used for in-gallery interactives when an object is shown to the public.",
            "value": "Inspired by the helmets worn by the first astronauts to walk on the moon, the Videosphere is made of synthetic materials that perfectly suit its cosmic aesthetic. While reflecting the period’s preoccupation with space exploration, the television also demonstrates innovative function: it can rotate 360 degrees on its pedestal, or, powered by a rechargeable battery, it can be removed and carried or hung by its chrome chain."
          },
          {
            "type": "general descriptionGeneral description (API) A broad description of the object to be used across various media.",
            "value": "Spherical red television (a) with convex screen at front and control knobs and hanging/carrying chain in indentation at top; chrome-plated telescoping attenna, top right. Sits in square red base (b) with circular indentation to hold television."
          },
          {
            "type": "digital table text",
            "value": "This portable television can rotate 360 degrees on its pedestal or can be carried by its chrome chain. The plastic housing reflects popular trends of the 1970s, including the use of bright, pop-art-inspired color and an interest in space exploration—the form is a nod to the Apollo 11 astronauts’ spherical helmets."
          }
        ],
        "exhibitionExhibition (API) A listing of exhibitions where an object was part of the display.": [
          {
            "collectionsOnlineId": "404734319",
            "datatype": {
              "base": "exhibition"
            },
            "date": [
              {
                "from": "2016",
                "to": "2017",
                "value": "2016-04-28-2017-03-12"
              }
            ],
            "department": [
              {
                "@admin": {
                  "id": "department-11",
                  "sourceSource (API) The origin of the data or object.": "tms",
                  "statusStatus (API) The state of the object as it refers to its ownership of the museum. The object may be accessioned, or on loan.": "public",
                  "uuidUUID (Computer Science) A universally unique identifier (UUID) is a 128-bit label used for information in computer systems. UUIDs are, for practical purposes, unique. Their uniqueness does not depend on a central registration authority or coordination between the parties generating them, unlike most other numbering schemes. While the probability that a UUID will be duplicated is not zero, it is close enough to zero to be negligible.": "075fcbc2-95a7-3e13-bb2d-aea4b03bcb9d"
                }
              }
            ],
            "id": "exhibition-1314",
            "identifier": [
              {
                "type": "tms id",
                "value": "1314"
              }
            ],
            "summary": {
              "title": "Energizing the Everyday: Gifts From the George R. Kravis II CollectionCollection (Museology) Museums are distinguished by their collection of unique objects that form the core of their activities for exhibitions, education, and research."
            },
            "title": [
              {
                "type": "default title",
                "value": "Energizing the Everyday: Gifts From the George R. Kravis II Collection"
              },
              {
                "type": "mnemonic",
                "value": "KRAVIS"
              },
              {
                "value": "Energizing the Everyday: Gifts From the George R. Kravis II Collection"
              }
            ],
            "venueVenue (API) The location of an exhibition.": [
              {
                "@admin": {
                  "id": "agent-3802",
                  "source": "tms",
                  "status": "public",
                  "uuid": "17aaf283-0f78-3723-83b6-f38b00deb8ea"
                }
              }
            ]
          },
          {
            "collectionsOnlineId": "1108750009",
            "datatype": {
              "base": "exhibition"
            },
            "date": [
              {
                "from": "2018",
                "to": "2019",
                "value": "2018-05-04-2019-03-17"
              }
            ],
            "department": [
              {
                "@admin": {
                  "id": "department-11",
                  "source": "tms",
                  "status": "public",
                  "uuid": "075fcbc2-95a7-3e13-bb2d-aea4b03bcb9d"
                }
              }
            ],
            "id": "exhibition-1527",
            "identifier": [
              {
                "type": "tms id",
                "value": "1527"
              }
            ],
            "label": [
              {
                "value": "Mounts"
              },
              {
                "value": "Light levels"
              },
              {
                "value": "Framing"
              }
            ],
            "summary": {
              "title": "Saturated: The Allure and Science of Color"
            },
            "title": [
              {
                "type": "default title",
                "value": "Saturated: The Allure and Science of Color"
              },
              {
                "type": "mnemonic",
                "value": "COLOR"
              },
              {
                "value": "Saturated: The Allure and Science of Color"
              }
            ],
            "venue": [
              {
                "@admin": {
                  "id": "agent-3802",
                  "source": "tms",
                  "status": "public",
                  "uuid": "17aaf283-0f78-3723-83b6-f38b00deb8ea"
                }
              }
            ]
          }
        ],
        "inscriptionInscription (Museology) words inscribed on the object itself, often by the manufacturer or designer to indicate origin, materials, date, or manufacturer details": [
          {
            "markings": "On bottom of screen: \r\nJVC VIDEOSPHERE on applied decal\r\nOn front of base:\r\nJVC molded in surface, painted white."
          }
        ],
        "geography": {
          "city": {
            "value": "Tokyo"
          },
          "country": {
            "value": "Japan"
          },
          "geocode": "manufactured in",
          "geocode_id": 5,
          "name": "Japan Tokyo"
        },
        "legalLegal (API) description of ownership, gift information, and public provenance.": {
          "credit": "Gift of George R. Kravis II",
          "rights": [
            {
              "details": "no information in file",
              "type": "copyrightCopyright (Museology) The status of an object's copyright is documented in the object record as image rights. This status determines what types of restrictions are applied to the reproduction of the image."
            }
          ]
        },
        "mediumMedium (Museology) Description of the material quality of the object or technical means of artistic expression, or production (such as metal, plastic, paint and canvas, sculptural stone, or code)": [
          {
            "value": "Acrylic"
          },
          {
            "value": "Chrome-plated metal"
          },
          {
            "value": "Metal"
          },
          {
            "value": "Plastic"
          }
        ],
        "measurements": {
          "dimensions": [
            {
              "value": "H x diam.: 36.2 × 24.1 cm (14 1/4 × 9 1/2 in.)"
            }
          ]
        },
        "multimediaMultimedia (API) A section of an API record that provides access to images, video, audio or other file associated with an object.": [
          {
            "datatype": {
              "actual": "image",
              "base": "media"
            },
            "id": "media-374839",
            "large": {
              "format": "jpeg",
              "locationLocation (Museology) The Location is the city, country, or region where the object was created": "374/839/large_CHSDM_285978_10.jpg",
              "measurements": {
                "dimensions": [
                  {
                    "dimension": "height",
                    "units": "pixels",
                    "value": 1024
                  },
                  {
                    "dimension": "width",
                    "units": "pixels",
                    "value": 1536
                  }
                ],
                "filesize": {
                  "units": "bytes",
                  "value": 144556
                }
              }
            },
            "preview": {
              "format": "jpeg",
              "location": "374/839/preview_CHSDM_285978_10.jpg",
              "measurements": {
                "dimensions": [
                  {
                    "dimension": "height",
                    "units": "pixels",
                    "value": 350
                  },
                  {
                    "dimension": "width",
                    "units": "pixels",
                    "value": 525
                  }
                ],
                "filesize": {
                  "units": "bytes",
                  "value": 57675
                }
              }
            },
            "summary": {
              "title": "CHSDM-285978_10"
            },
            "type": "image"
          }
        ],
        "name": [
          {
            "value": "portable television"
          }
        ],
        "note": nullNull (Computer Science) No value or content,
        "period": null,
        "provenanceProvenance (Museology) A record of ownership of a work of art or an antique, used as a guide to authenticity or quality.": [
          "2016: Promised to Cooper Hewitt by George R. Kravis II"
        ],
        "status": {
          "value": "Accessioned object"
        },
        "makerMaker (API) Creator of an object": [
          {
            "id": "agent-21051",
            "summary": {
              "title": "Victor Company of Japan, Ltd."
            }
          }
        ]
      }
    ]
  },
  "extensions": {
    "pagination": {
      "hits": 1,
      "per_page": 10,
      "current_page": 0,
      "number_of_pages": 1
    }
  }
}

Objects

To access the museum’s objectsObjects (API) The dataset containing all objects held within the Cooper Hewitt's online collection data, the following queryQuery (Computer Science) A query is a request for data or information from a database table or combination of tables, or an API that manages access to those tables will display all the available fieldsFields (Computer Science) The smallest container of information in a database. A field is named, e.g. "Title" or "Date" and each record contains a group of fields.:

{
  objectObject (Museology) Artefact or specimen held in a museum collection.

(Computer science) A software "bundle" consisting of a set of variables which define the states the object can exist in and a set of functions that define its behavior. {
    titleTitle (Museology) The name given to the design or work of art.
    summary
    identifierIdentifier (API) A group of fields containing different unique identifiers for an object, agent, exhibition, or other unique datatype
    id
    classificationClassification (API)  A formal terminology that can be applied to any object. Objects can have more than one classification.
    culture
    dateDate (Museology) The date range of the creation of the object. This value will have  'from', and 'to' key value pairs.
    departmentDepartment (API) The section of the museum that an object is associated with.
    descriptionDescription (API) Long-form, curatorial,  interpretive text created for context and additional descriptive elements.
    exhibitionExhibition (API) A listing of exhibitions where an object was part of the display.
    inscriptionInscription (Museology) words inscribed on the object itself, often by the manufacturer or designer to indicate origin, materials, date, or manufacturer details
    geography
    legalLegal (API) description of ownership, gift information, and public provenance.
    loaned
    locationLocation (Museology) The Location is the city, country, or region where the object was created
    material
    mediumMedium (Museology) Description of the material quality of the object or technical means of artistic expression, or production (such as metal, plastic, paint and canvas, sculptural stone, or code)
    measurements
    multimediaMultimedia (API) A section of an API record that provides access to images, video, audio or other file associated with an object.
    name
    note
    period
    provenanceProvenance (Museology) A record of ownership of a work of art or an antique, used as a guide to authenticity or quality.
    statusStatus (API) The state of the object as it refers to its ownership of the museum. The object may be accessioned, or on loan.

    agent {
        id
        summary
    }

    collector {
        id
        summary
    }

    makerMaker (API) Creator of an object {
        id
        summary
    }

    subject {
        id
        summary
    }

    tag {
        id
        summary
    }   
  }
}

Size	Page	Rows returned
250	1	1 – 250
250	2	251 – 500
250	3	501 – 750

View As...

API Documentation

Getting Started

Start making queries

Incorporate the API in your code

Open access

GraphQL

Anatomy of a Record

Objects

Images and other media

Resized media (images)

Example

Zooms

Creative Commons

Limiting your query to just the media artifacts that you need

Colors

Search for objects

Searching between years

Sorting results

Pagination

More complex searches

Agents

Search for agents

Sorting agents

Department

Exhibitions

Locations

Tags

Tags

Terms

Nested queries

Agents on objectsObjects (API) The dataset containing all objects held within the Cooper Hewitt's online collection

Objects on Agents

Aggregations

Example Queries