Efemerides 2.0

Efemérides, acontecimientos, nacimientos y defunciones

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://efemerides20.com/api?<parametro 1>&<parametro 2>&<parametro n>

3. Parametros

ParametroTipoDescripción
keyobligatorio, cadena de textoPara poder utilizar la API necesitas una clave única que se puede solicitar pinchando aquí.
monthobligatorio, número enteroNúmero del 1 al 12 que representa el mes sobre el que solicitamos la información.
dayobligatorio, número enteroNúmero del 1 al 31 que representa el día del mes sobre el que solicitamos la información.
typecadena de texto (all, event, birth, death)Mediante este parametro se puede elegir que tipo de efeméride se quiere. Por defecto salen todas.
[obsoleto] 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.
limitnúmero enteroSolo es necesario si la opción random ha sido elegida y determina el número de efemerides a mostrar. Por defecto es 1.
outputcadena 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://efemerides20.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://efemerides20.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://efemerides20.com/api?key=XXXXXX&day=4&month=12&output=json&type=birth

La petición anterior devolvería un nacimiento 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
contentContenido de la efemérideDevuelve el contenido de la efeméride, el texto explicativo de lo sucedido ese día.
typeTipo 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.
dateFecha de la efemérideDí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.