Open Archives API » Stats/Breakdown

Returns record counts filtered by any combination of archive, source type, event type, place and year range, grouped by one chosen dimension. Useful for cross-tabulation questions such as "which archives hold prayer card collections?" or "how many marriages per year in Amsterdam?".

URL

https://api.openarchieven.nl/1.1/stats/breakdown.json

Method

GET

Input

Name	Required	Description	Default
group_by	Yes	Dimension to aggregate on. One of: archive, sourcetype, eventtype, place, year.
archive_code	No	Code of archive (obtain a list of valid archive codes via Stats/Archives). Prefix with ! to negate (e.g. !saa excludes Stadsarchief Amsterdam).
sourcetype	No	Source type to filter on. Multiple source types can be combined with & (space-amp-space).
eventtype	No	Numeric value depicting the event type: 0 - All types 1 - Christening and birth records 2 - Marriage records 3 - Burial and death records 6 - Notarial deeds	0
eventplace	No	Existing place name to filter on (exact match).
year_start	No	Starting year of events to include (minimum=1500). Alias eventyearstart is also accepted.	(unfiltered)
year_end	No	Ending year of events to include (maximum=1960). Alias eventyearend is also accepted.	(unfiltered)
min_count	No	Exclude groups with fewer records than this threshold.	1
number_show	No	Maximum number of groups returned (maximum=500).	100
sort	No	Sort order of the returned groups: count_desc, count_asc, or name_asc (alphabetical by key).	count_desc
lang	No	Language code (nl for Dutch, en for English, de for German, fr for French) for sourcetype and eventtype labels. Only nl and en are localised; de and fr fall back to nl.	nl
callback	No	Function name to be called on JSON data (JSONP).

Output

The output is a JSON object containing the chosen group_by dimension, an echo of the supplied filters, the total filtered record count, the total number of distinct groups (capped at 750) and an array of result rows.

Example: https://api.openarchieven.nl/1.1/stats/breakdown.json?group_by=archive&sourcetype=Bidprentjesverzameling outputs (pretty-printed):

{
    "group_by": "archive",
    "filters": {
        "sourcetype": "Bidprentjesverzameling"
    },
    "total_records": 2991005,
    "total_groups": 47,
    "results": [
        {
            "key": "hwh",
            "label": "Heemkundekring Weerderheem",
            "count": 201236
        },
        {
            "key": "bhi",
            "label": "Brabants Historisch Informatie Centrum",
            "count": 187543
        }
.....
    ]
}

Errors

One of the following errors may be thrown:

Error code	Error message
1	Invalid archive
4	Invalid lang
23	Value of number_show exceeds defined maximum
25	Value of eventyearstart is below defined minimum
26	Value of eventyearend exceeds defined maximum
28	Invalid eventype
46	Invalid group_by
47	Missing required group_by
48	Invalid sort
49	Invalid min_count

An example error looks (pretty-printed) like:

{
    "error_code": 47,
    "error_description": "Missing required group_by"
}

Back to API documentation