Data Delivery

The DIAMM API provides a machine-readable interface to the DIAMM data. We offer content negotiation for HTML and JSON representations of all DIAMM records. The easiest way to view the JSON representation of a record is by appending "format=json" as a query parameter on the URL. For example,

Scripted access can use the Accept header to request JSON response, using the 'application/json' MIME type. Using the cURL command-line utility, such a request might look like this:

$> curl -H "Accept: application/json"

If you use the Python Requests module in a script, a similar request might look like this:

r = requests.get("", headers={"Accept": "application/json"})

Within the JSON response, related entities will usually return a "url" property, pointing to the record for that relationship.

Search API

The search system also operates over a REST API. There are two parameters one can pass as query parameters to the /search/ endpoint: q, for a full-text record search, and type, to limit results to a particular type of record. Consider, for example, the following URL request: Clicking on this in your browser will return a list of search results. However, the same result is JSON-serializable with content negotiation, and will perform a full-text search, returning a JSON-formatted search result for all records containing the word "byrd" in them.

The "type" parameter restricts the type to a certain type of record. The types available are:

  • all (the default): Returns records of all types
  • archive: returns only archive records
  • source: returns only source records
  • sources_with_images: returns only source records that have viewable images
  • person: returns only person records
  • organization: returns only organization records
  • set: returns only set records
  • composition: returns only composition records

The result returned will be appropriate for pagination. It will give absolute URLs to the next and previous pages, the number of pages, and absolute links to each of the pages. It will also contain counts for each of the other types of records.

If you wish to create more complex searches, you can experiment with the search interface, adding and removing parameters using the facet blocks. If you wish to translate that to a machine-readable representation, you can append "&format=json" on the URL, or use content negotiation as described above.