> Also available in English: https://cubaresearchproject.com/developers/ # 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 | Recurso | Dirección | | --- | --- | | Índice de la API | [/api](/api) | | Especificación OpenAPI 3.1 | [/api/openapi.json](/api/openapi.json) | | Documentación interactiva | [/api/docs](/api/docs) | | Guía para agentes (llms.txt) | [/llms.txt](/llms.txt) | | Guía completa para agentes | [/llms-full.txt](/llms-full.txt) | | Mapa del sitio | [/sitemap.xml](/sitemap.xml) | | Catálogo de la API (RFC 9727) | [/.well-known/api-catalog](/.well-known/api-catalog) | ## 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](/es/contact).