API y documentación para desarrolladores de Cuba Research Project
El archivo de Cuba Research Project puede leerse tanto por personas como por máquinas. Todo lo que aparece en esta página es público, no necesita clave y se sirve desde
Referencia rápida
Endpoints REST públicos
Todas las respuestas son JSON. Solo GET; sin autenticación.
GET /api/health: comprobación de vida. Devuelve {"status":"ok"}.
GET /api/meta: la forma del archivo: cada colección con su número de registros, los tipos de registro en uso y el total de personas indexadas.
GET /api/collections: el listado completo de colecciones, una entrada por conjunto de datos, cada una con la dirección de su propia página en este sitio.
GET /api/search: la búsqueda que usa este sitio. Parámetros: q (nombre completo), given, surname, surname2, place, dataset (id), type (id del tipo de registro), yfrom / yto (año del evento), bfrom / bto (año de nacimiento), dfrom / dto (año de defunción), sort, page y source (records, trees o ambos). Devuelve total, page, page_size, pages, rows y los recuentos por tipo de registro y colección. Cada página trae 24 filas.
GET /api/suggest: sugerencias sobre el índice de nombres. Acepta los mismos parámetros de nombre que la búsqueda y devuelve los nombres coincidentes más frecuentes.
GET /api/record/{record_id}: un registro completo, con su colección, tipo de registro, fuente y los campos tal como fueron transcritos. Devuelve 404 cuando el registro no existe.
GET /api/record/{record_id}/companions: las demás personas nombradas en el mismo documento.
GET /api/person/{person_id}/main-record: el registro al que pertenece una persona.
GET /api/stats/imports: serie diaria de registros añadidos al archivo.
GET /api/random: una persona al azar, para descubrir.
Ejemplo
Buscar personas cuyo apellido paterno se parezca a Valdés, nacidas entre 1880 y 1900:
curl "/api/search?surname=Valdes&bfrom=1880&bto=1900"
Los nombres se comparan sin distinguir acentos ni mayúsculas, de modo que Valdes y Valdés devuelven las mismas personas.
Markdown para agentes
Cada página de contenido de este sitio se publica también en Markdown. Se pide mediante negociación de contenido:
curl -H "Accept: text/markdown" /es/developers/
La versión en Markdown de una página tiene además una dirección propia y estable: se antepone /md a la ruta de la página y se añade index.md, como en /md/es/developers/index.md. Las respuestas negociadas llevan Vary: Accept, Accept-Encoding. Una petición que solo acepte Markdown para una página que no tiene versión en Markdown se responde con 406 Not Acceptable.
Errores
Las rutas inexistentes devuelven un 404 real, con un cuerpo breve en Markdown para los clientes que no pidieron HTML. Nada en este sitio responde a una página que no existe con un 200.
Condiciones
El archivo se ofrece para investigación y uso personal. Identifica tu cliente con un User-Agent descriptivo, mantén un ritmo de peticiones razonable y cita a Cuba Research Project cuando publiques algo construido sobre él. Preguntas: escríbenos.
Search the archive · All collections · Sitemap