Cuba Research Project API and Developer Documentation
The Cuba Research Project archive is readable by machines as well as by people. Everything on this page is public, needs no key, and is served from
Quick reference
Public REST endpoints
All responses are JSON. GET only; no authentication.
GET /api/health: liveness. Returns {"status":"ok"}.
GET /api/meta: the archive's shape: every dataset with its record count, the record types in use, and the total number of indexed people.
GET /api/collections: the full collection listing, one entry per dataset, each with the URL of its own page on this site.
GET /api/search: the search that powers this site. Parameters: q (whole name), given, surname, surname2, place, dataset (id), type (record-type id), yfrom / yto (event year), bfrom / bto (birth year), dfrom / dto (death year), sort, page, and source (records, trees, or both). Returns total, page, page_size, pages, rows, and facet counts by record type and collection. Pages hold 24 rows.
GET /api/suggest: typeahead over the name index. Takes the same name parameters as search and returns the most frequent matching names.
GET /api/record/{record_id}: one record in full, including its dataset, record type, source, and the fields as transcribed. 404 when the record does not exist.
GET /api/record/{record_id}/companions: the other people named on the same document.
GET /api/person/{person_id}/main-record: the record a person belongs to.
GET /api/stats/imports: a daily series of records added to the archive.
GET /api/random: a random person, for discovery.
Example
Search for people whose paternal surname resembles Valdés, born between 1880 and 1900:
curl "/api/search?surname=Valdes&bfrom=1880&bto=1900"
Names are matched accent- and case-insensitively, so Valdes and Valdés return the same people.
Markdown for agents
Every content page on this site is also published as Markdown. Ask for it with content negotiation:
curl -H "Accept: text/markdown" /developers/
The Markdown variant of a page also has a stable address of its own: append the page's path to /md and add index.md, as in /md/developers/index.md. Negotiated responses carry Vary: Accept, Accept-Encoding. A request that will accept only Markdown for a page that has no Markdown variant is answered with 406 Not Acceptable.
Errors
Unknown paths return a real 404, with a short Markdown body for clients that did not ask for HTML. Nothing on this site answers a missing page with a 200.
Terms
The archive is offered for research and personal use. Please identify your client with a descriptive User-Agent, keep request rates civil, and credit Cuba Research Project when you publish anything built on it. Questions: contact us.
Search the archive · All collections · Sitemap