Causa General search API

Search words and phrases in the OCR text of the Causa General (Archivo Histórico Nacional, published on PARES). Returns context snippets and locations, never whole pages or the corpus.

IMPORTANT: the source is an instruction compiled by the Franco regime; it contains accusations and statements that were never verified. The text is automatic OCR and contains errors, and handwritten pages are not read yet. A name that does not appear is not proof that it is absent from the archive. Every response carries this notice in the notice field.

Operation

GET /api/search?q=<tag>&q=<tag>&province=<value>&lang=en

The same parameters can be sent as a JSON body with POST /api/search ({"q": ["<tag>"], "province": ["<value>"], "lang": "en"}), so that search terms do not appear in URLs or in intermediary logs. The response is identical.

• q: one search tag, repeatable. A tag with a single word matches it with fuzziness. A tag with several words (q=alcalde de Olot, with or without double quotes) is an exact phrase: same order, no words in between and no fuzziness. All tags must appear together on the page, in any order, with at most 3 words in between. A tag starting with - (q=-casamort, or q=-"jose maria" for a phrase) hides the matches whose highlighted text contains that exact word or phrase (case and accents ignored, no fuzziness); other matches on the same page are kept. At least one non-excluded tag is required.
• source, province, piece, judicial_district: filters, repeatable (any of the given values matches). source is the archival collection: causa_general (Causa General, provincial files) or tribunales_populares (Tribunales Populares y Jurados de Urgencia y de Guardia de Madrid, 1936). The other three are described below.
• lang: language of messages and of the notice (ca default, es, gl, eu, oc; any other falls back to ca).

Case and accents are ignored (masferre finds Masferré; ç = c and ñ = n). Fuzzy matching tolerates OCR errors depending on word length: under 4 letters, none; 4 to 7 letters, 1 edit; 8 or more, 2 edits.

Archive terms are kept in the original language: province, piece (pieza) and judicial_district (partido judicial) values are Spanish, as in PARES.

Limits (the same for people and agents)

• At least 3 characters in total, at most 6 words in total and 100 characters per tag.
• At most 200 results per query. To see more, narrow the query with filters.
• Snippets of about 100 characters on each side of the match.
• Maximum time per query: 500 ms.
• Exact totals (per occurrence) are only computed when the query, once filters are applied, matches at most 700 pages. Above that the response is partial: total, exact and approximate are null, pages gives the number of matching pages, only up to 200 occurrences are returned: the first half exact and the rest approximate (archive order within each group; a group that has fewer gives its unused slots to the other) and facets counts are per page. Add more tags or filters to get exact totals.
• 30 requests per minute per IP address, and at most 4 simultaneous searches.
• When a limit is exceeded: HTTP 429 with a Retry-After header (seconds to wait).
• There is no operation that returns a whole page or the corpus.

Response (200, JSON)

{
  "total": 16, "exact": 10, "approximate": 6, "partial": false, "pages": null, "facets_unit": "occurrences",
  "ms": 46, "truncated": false, "max_results": 200,
  "notice": "…",
  "facets": { "source": [["causa_general", 16]], "province": [["Barcelona", 12], ["Girona", 4]], "piece": […], "judicial_district": […] },
  "results": [ {
    "source": "causa_general", "province": "Barcelona", "piece": "…", "judicial_district": null,
    "shelfmark": "FC-CAUSA_GENERAL,1630,Exp.1", "image": 369, "total_images": 424, "pares_id": "5545508",
    "exact": true, "distance": 0, "doubtful": false,
    "before": "…preceding text", "match": [ {"text": "…"}, {"text": "Masferrer", "hit": true, "fuzzy": false, "distance": 0} ], "after": "following text…",
    "variants": [], "pares_url": "https://pares.cultura.gob.es/…/show/5545508?txt_id_imagen=369"
  } ]
}

• total, exact, approximate: occurrences in total, exact and approximate (all null when partial is true, and then pages is the number of matching pages, a count that does not enforce word proximity). facets_unit: occurrences or pages. facets: per-value counts for each filter, computed with the other filters applied but not its own. truncated: more results exist than the 200 returned.
• There is a single list. Each page is ranked by its best match: the one with the smallest total weighted Levenshtein distance between the searched words and the words found in the text (distance, 0 = exact; exact is distance == 0). The weighting only orders the results, it never adds or removes any: what matches is decided by plain Levenshtein distance. Substitutions between letters that this OCR often confuses (a/e, e/o, a/o, a/u, i/e, i/l, i/1, l/1, c/e, c/o, n/m, n/u, v/y, f/t, a/d, a/s, a/i, n/r, e/s, c/g, i/t) cost 0.5 and every other edit costs 1, so distance can be a half-integer. Ties are broken by the number of occurrences at that distance (more first), then by more reliable OCR, then by archive order (province, shelfmark, image). Rows of the same page stay together, ordered by distance and position. Of the 200 rows, 40 are reserved for approximate matches when there are enough of them, so exact matches cannot hide them. In partial mode (very frequent words) only a subset of the pages is checked: exact matches are chosen by text relevance and approximate ones by archive order, and the same ranking is applied to what was checked. The order is stable: the same query always returns the same list.
• match: segments of the snippet; those with hit: true are matched words, distance is the weighted Levenshtein distance of that word to the searched one (0 = exact), and fuzzy: true marks an approximate variant (the spelling actually found is in variants).
• doubtful: the OCR confidence for that page is low.
• shelfmark: shelfmark (signatura); image: image number within the unit; total_images: images in the unit; pares_id: PARES identifier of the unit.
• pares_url: the PARES record of the unit, opened directly on that image in the PARES viewer (?txt_id_imagen=<image>). It may be null if links have been disabled.

Errors

{"error": {"code": "too_short", "message": "…", "params": {"n": 3}}, "notice": "…"}

Codes: empty, too_short, too_many_words, tag_too_long, timeout (HTTP 400); rate_limited, busy (HTTP 429).

Other endpoints

• GET /api/languages: available interface languages (code, name).

Terms of use

If you reuse results, cite the source following the instructions of PARES (the Spanish archives portal), not this service, and do not present results as official: this project is independent and has no connection with the Spanish Ministry of Culture. Do not crawl the HTML: this API is the intended way in.

← Search · llms.txt