Documentación de la API de Efemerides 2.0
1. Introducción
La API de Efemerides 2.0 es capaz de proporcionar todos los datos de los que disponemos en Efemerides 2.0. La API devolverá un documento XML, JSON o con formato serialize de PHP en respuesta a una petición web. El contenido de ese documento puede variar dependiendo de los datos que se pidan en la petición, cada petición ha de referirse a un día del año.
2. Formato de la URL
http://efemerides.berriart.com/api?<parametro 1>&<parametro 2>&<parametro n>
3. Parametros
| Parametro | Tipo | Descripción |
|---|---|---|
| key | obligatorio, cadena de texto | Para poder utilizar la API necesitas una clave única que se puede solicitar pinchando aquí. |
| month | obligatorio, número entero | Número del 1 al 12 que representa el mes sobre el que solicitamos la información. |
| day | obligatorio, número entero | Número del 1 al 31 que representa el día del mes sobre el que solicitamos la información. |
| type | cadena de texto (all, event, birth, death) | Mediante este parametro se puede elegir que tipo de efeméride se quiere. Por defecto salen todas. |
| what | cadena de texto (all, random) | Se puede elegir entre dos tipos. all mostrará todas las efemérides de ese día y del tipo indicado. random mostrará efemérides aleatorias de ese día y del tipo indicado, es la opción por defecto. Al elegir random debes poner un límite de respuestas a mostrar. |
| limit | número entero | Solo es necesario si la opción random ha sido elegida y determina el número de efemerides a mostrar. Por defecto es 1. |
| output | cadena de texto (php, xml, json) | Indica el formato de salida de la información. Por defecto sale con formato serialize de php, aunque se puede solicitar en también en XML y JSON. |
4. Ejemplos de peticiones
http://efemerides.berriart.com/api?key=XXXXXX&day=4&month=12
La petición anterior devolvería una efeméride al azar del día 4 de diciembre en formato serialize de PHP.
http://efemerides.berriart.com/api?key=XXXXXX&day=4&month=12&limit=5&output=xml
La petición anterior devolvería cinco efemérides al azar del día 4 de diciembre en formato XML.
http://efemerides.berriart.com/api?key=XXXXXX&day=4&month=12&output=json&what=all&type=birth
La petición anterior devolvería todos los nacimientos del día 4 de diciembre en formato JSON.
5. Respuesta
La respuesta serán varias o una sola efeméride. Por cada una de ellas se devolveran tres atributos:
| Atributo | ¿Qué es? | Descripción |
|---|---|---|
| content | Contenido de la efeméride | Devuelve el contenido de la efeméride, el texto explicativo de lo sucedido ese día. |
| type | Tipo de efeméride (event, birth, death) | Hay tres tipos de efemérides en la web, este atributo indica a cual pertenece. event -> evento, birth -> nacimiento, death -> defunción. |
| date | Fecha de la efeméride | Día en el que se produjo la efeméride indicada. |
Ejempo de respuesta en formato serialize de PHP:
a:5:{i:0;a:3:{s:7:"content";s:44:"Fray Domingo de Salazar, religioso español.";s:4:"date";s:10:"1594-12-04";s:4:"type";s:5:"death";}i:1;a:3:{s:7:"content";s:33:"Deanna Durbin, actriz canadiense.";s:4:"date";s:10:"1921-12-04";s:4:"type";s:5:"birth";}i:2;a:3:{s:7:"content";s:41:"Ivana Kobilca, pintora realista eslovena.";s:4:"date";s:10:"1926-12-04";s:4:"type";s:5:"death";}i:3;a:3:{s:7:"content";s:94:"Un mono regresa a la tierra sano y salvo después de estar a 55 millas en el espacio exterior.";s:4:"date";s:10:"1959-12-04";s:4:"type";s:5:"event";}i:4;a:3:{s:7:"content";s:39:"Julio Ramón Ribeyro, escritor peruano.";s:4:"date";s:10:"1994-12-04";s:4:"type";s:5:"death";}}Ejempo de respuesta en formato JSON:
[{"content":"Jeremiah Horrocks hace las primeras observaciones sobre el tr\u00e1nsito de Venus.","date":"1639-12-04","type":"event"},{"content":"B\u00e1rbara Herbella, actriz espa\u00f1ola conocida como B\u00e1rbara Lamadrid.","date":"1812-12-04","type":"birth"},{"content":"Espa\u00f1a: Los Voluntarios de la Libertad inician en El Puerto de Santa Mar\u00eda (C\u00e1diz) una insurrecci\u00f3n, dirigida por el anarquista Ferm\u00edn Salvochea.","date":"1868-12-04","type":"event"},{"content":"Jim Hall, guitarrista de jazz estadounidense.","date":"1930-12-04","type":"birth"},{"content":"Tommy Bolin, gutiarrista estadounidense (Deep Purple).","date":"1976-12-04","type":"death"}]Ejempo de respuesta en formato XML:
<?xml version="1.0" encoding="UTF-8" ?>
<efemerides>
<item>
<content>Bárbara de Braganza, reina consorte de España.</content>
<date>1711-12-04</date>
<type>birth</type>
</item>
<item>
<content>Melesio Morales, compositor mexicano</content>
<date>1839-12-04</date>
<type>birth</type>
</item>
<item>
<content>Gemma Jones, actriz británica.</content>
<date>1942-12-04</date>
<type>birth</type>
</item>
<item>
<content>Sylvester Terkay, luchador profesional estadounidense.</content>
<date>1970-12-04</date>
<type>birth</type>
</item>
<item>
<content>Martell Webster, baloncestista estadounidense.</content>
<date>1986-12-04</date>
<type>birth</type>
</item>
</efemerides>6. Límites
En un principio no hay un límite de peticiones diarias, pero recomiendo usar la api con moderación. Siempre que se pueda, es mejor hacer una sola petición con todas las efemerides de un día y guardarlas para luego mostrarlas al gusto, a hacer una petición por página vista. Si más adelante tengo problemas con el servidor nos verémos obligados a limitar las consultas.
7. Otros
En el caso de que decidas usar la API, sería de agradecer un enlace hacia Efemerides 2.0 o a Berriart, aunque sea en el lugar más recóndito de tu web. Si tienes alguna duda o encuentras algún bug puedes enviar un mail a la dirección: efemerides[at]berriart[dot]com.