API V1 Documentation

Overview

The EHRI JSON API is currently in testing and not recommended for use in important applications.

The EHRI portal has an experimental web API, intended for searching and retrieving a subset of EHRI data in structured JSON format. While it is intended that the scope of the API will broaden in future, it is intended to prioritise convenience over semantic precision, providing a somewhat simplified view of EHRI's data relative to that offered by the HTML site.

At present, information is only available for four types of item:

  1. Countries (type: Country)
  2. Institutions (type: Repository)
  3. Archival descriptions (type: DocumentaryUnit)
  4. Authorities (also known as Historical Agents, type: HistoricalAgent)

The base API URL is /api/v1.

Actions

Three "actions" are currently available:

  1. Global search at /search: Intended for a simple-text query of all country report, institution, and archival description information in the portal. Optionally, the search can be limited to items of specific types.
  2. Retrieving item info by ID at /{ID} : If item's IDs are known in advance (or determined via a search), information about them can be fetched individually.
  3. Item-scoped search at /{ID}/search : Intended for searching via simple text query within the "scope" of a particular item, retrieving matching child items. For example, a country can be searched for specific repositories, and repositories and archival descriptions for, respectively, top-level and sub-level descriptions.

The format of returned data conforms to the http://jsonapi.org/ specification and has content-type application/vnd .api+json.


The Global search action (/search) allows you to search all available item types. Four parameters are currently supported:

q
A text query, following the same rules as searching on the portal site.
type
One of the available data types. Can be used multiple times.
page
Since results are paginated, this number selects the desired page.
limit
The number of results to fetch per page, up to a maximum of 100.

Test it!




Run it as a curl command:

curl "https://portal.ehri-project.eu/api/v1/search"

Retrieve an item

For retrieving individual items (of any type) the /{ID} action is provided, with the {ID} being the global EHRI identifier of the item you want.

Test it!




Run it as a curl command:

curl "https://portal.ehri-project.eu/api/v1/us-005578"

The item search action (/{ID}/search) allows you to search within an individual item, for example: searching the archival descriptions within a particular repository. The same four parameters as the Global Search action are supported

q
A text query, following the same rules as searching on the portal site.
type
One of the available data types. Can be used multiple times.
page
Since results are paginated, this number selects the desired page.
limit
The number of results to fetch per page, up to a maximum of 100.

Test it!






Run it as a curl command:

curl "https://portal.ehri-project.eu/api/v1/us-005578/search"

Structure of responses

The responses from the API conform to the http://jsonapi.org specification, so read the documentation there for an overview of what to expect.

The response is a JSON object with up to four fields:

data
this contains the main body of the response, and is either a list of items or a single item.
links
the top level "links" field contains links to API actions related to this one. For example, it contains links to the first, last, next, and previous pages if the data is paginated.
included
contains a list of related items. For example, when searching within an item , the item itself is included with the response, for convenience.
meta
contains additional relevant metadata, for example the total number of items, and the total number of pages.

Each item type has a different set of possible fields. The naming of the fields for DocumentaryUnit, HistoricalAgent, Repository items respectively generally conform to the ISAD(G), ISAAR, and ISDIAH standards. Look at the example responses for an idea of what to expect.

Example usage with Python

The script shown below is a Python script for creating a tab-delimited (TSV) file containing three fields: the EHRI item id, its title, and the scope and content field of EHRI archival descriptions.

You can copy the code to a file called scopecontent.py and run it with URL for a search of EHRI archival descriptions, e.g:

python3 scopecontent.py "https://portal.ehri-project.eu/api/v1/search?type=DocumentaryUnit&q=title:Amsterdam"
        

This will run a search for documentary unit items with "Amsterdam" in the title and download all the subsequent pages of items, transforming the selected data to TSV and printing it to the console.