Open Archives API » Transcriptions/Search

Performs a full-text search across the page transcriptions of historical documents indexed by Open Archives. Mirrors the search UI at /transcripties/zoek.php.

Results are ordered by Elasticsearch relevance (the order is fixed and cannot be overridden) and are returned paginated. Each match includes a source citation, page identifier and up to five highlighted text fragments. The set of facets returned depends on the supplied filters: with no archive_code the response carries a source_archive facet; with only archive_code set, an archive_number facet; with both archive_code and archive_number set, an inventory_number facet.

URL

https://api.openarchieven.nl/1.1/transcriptions/search.json

Method

GET

Input

Name	Required	Description	Default
q	Yes	Search query. Wrap in double quotes for an exact phrase, include * or ? for wildcard matching, otherwise the words are combined with an AND operator. Special characters [ ] ( ) { } ^ + = ! ~ : - / are stripped.
archive_code	No	Filter on a specific source archive. Obtain valid codes via Stats/Archives.
archive_number	No	Filter on a specific archive number (archieftoegang) within archive_code. Only meaningful when archive_code is also set.
inventory_number	No	Filter on a specific inventory number within archive_number. Only meaningful when both archive_code and archive_number are set.
year_start	No	Filter on the start year of the inventory the page belongs to.
year_end	No	Filter on the end year of the inventory the page belongs to.
number_show	No	Number of results to return per page (max 100).	10
start	No	Result offset for paging.	0
lang	No	Language code (nl, en, de, fr) used to localise the archive name.	nl
callback	No	Function name to be called on JSON data (JSONP).

Output

JSON object with three top-level fields: query (echo of the supplied parameters), response.number_found (total matches), response.docs (current page of matches), and response.facets (one of source_archive, archive_number or inventory_number depending on the filters).

Each match in response.docs contains: id, uri, source_archive (with isil, archive_code, name), optional archive_number and inventory_number objects, page, and snippets — an array of up to five highlighted text fragments wrapping the matched terms in <em>...</em>.

Example: https://api.openarchieven.nl/1.1/transcriptions/search.json?q=coret&number_show=2&format=json outputs (pretty-printed):

{
    "query": {
        "q": "coret",
        "archive_code": null,
        "archive_number": null,
        "inventory_number": null,
        "year_start": null,
        "year_end": null,
        "start": 0,
        "number_show": 2,
        "language": "nl"
    },
    "response": {
        "number_found": 1128,
        "docs": [
            {
                "id": "NL-HaNA_1.04.02_8068_0088",
                "uri": "https://www.openarchieven.nl/transcripties/toon/NL-HaNA_1.04.02_8068_0088",
                "source_archive": {
                    "isil": "NL-HaNA",
                    "archive_code": "rzh",
                    "name": "Nationaal Archief"
                },
                "archive_number": {
                    "nr": "1.04.02",
                    "title": "Inventaris van het archief van de Verenigde Oost-Indische Compagnie (VOC), 1602-1795 (1811)",
                    "url": "https://www.nationaalarchief.nl/onderzoeken/archief/1.04.02"
                },
                "inventory_number": {
                    "nr": "8068",
                    "title": "Kamer Zeeland, ingekomen stukken ... 1692",
                    "url": "https://www.nationaalarchief.nl/onderzoeken/archief/1.04.02/invnr/8068"
                },
                "page": "88",
                "snippets": [
                    "wel <em>Coret</em> aen sComp. s bediende te koop hebben gebragt",
                    "geen <em>Coret</em> meer wisselen"
                ]
            }
        ],
        "facets": {
            "source_archive": [
                { "isil": "NL-HaNA",   "archive_code": "rzh", "name": "Nationaal Archief",      "count": 986 },
                { "isil": "NL-AsdSAA", "archive_code": "saa", "name": "Stadsarchief Amsterdam", "count":  74 }
            ]
        }
    }
}

Example: search filtered by archive: https://api.openarchieven.nl/1.1/transcriptions/search.json?q=coret&archive_code=hua&number_show=2&format=json — the response then contains an archive_number facet instead of source_archive.

Errors

One of the following errors may be thrown:

Error code	Error message
1	Invalid archive
4	Invalid lang
9	Invalid years
15	Missing required format specification
21	Missing required name
23	Value of number_show exceeds defined maximum

An example error looks (pretty-printed) like:

{
    "error_code": 21,
    "error_description": "Missing required name"
}

Back to API documentation