Como interactuar con el API
De Wiki
Contenido |
Descripción Técnica
- El API desarrollado en esta primera versión es del tipo REST, es decir, se obtendrá la data realizando llamadas HTTP mediante URI utilizando el método GET como método exclusivo de acceso.
- En esta primera versión se puede obtener las últimas noticias publicadas.
- El acceso es indicando el tipo de consulta, el número de noticias y lo más importante, el key de acceso.
Consideraciones Generales
- El acceso está limitado a 500 llamadas por día.
- En primera instancia, el modo de acceso a los servicios del API es autentificado con un [ key ] que se incluira en la URI.
- El parámetro obligatorio es el key de acceso.
- Si no se incluye el [key] o se hace de modo incorrecto (key no registrado), se mostrará el mensaje "Acceso Denegado".
API : Flujo de noticias
La URI estará formada del siguiente modo:
/ api/news.json?cat=[categoria]&n=[numNoticias]&key=[keyAcceso]
El parámetro [n] es opcional.
- El parámetro [n] debe ser un valor numérico. Si no es definido correctamente, se devolverá un mensaje indicando que existe un error en dicho parámetro.
- Si en la petición no se define [n] , entonces el sistema devolverá el número máximo de noticias permitidas.
- Si se define [n], el sistema devolverá el número especificado de noticias.
- El sistema devuelve por defecto 36 noticias como máximo por llamada.
El parámetro [cat] es opcional.
- Las categorías permitidas son:
[politica] [lima] [peru] [mundo] [economia] [tecnologia] [deportes] [espectaculos] [gastronomia] [opinion]
- Si en la petición no se define [cat] , entonces el sistema devolverá las últimas noticias en general.
- Si se define [cat], el sistema devolverá las últimas noticias de la categoría especificada.
- La data básica que devuelve el sistema por noticia está compuesta por: id, titulo, bajada y url.
Data Devuelta
El sistema devolverá la data en formato Json. La data es un array multidimensional conformado por una 'Cabecera' y la propia 'Data'. A continuación se detalla:
- INFO
-> [site]: Proveedor de Noticias, El Comercio
-> [type]: Tipo de consulta hecha.
-> [cat]: Categoría de las noticias devueltas.
-> [n]: Número de resultados devueltos.
- DATA
-> [nid]: Id de la noticia.
- title: Título de la noticia.
- extract: Extracto (bajada) de la noticia.
- url: URL de la noticia en la Web El Comercio.
- date: Fecha de publicación de la noticia.
- timestamp: Timestamp de la fecha de publicación (Hora de Lima, Perú).
Ejemplos
Para obtener las últimas noticias, la URI será:
http://elcomercio.pe/api/news.json?key=2c17325ef5e7f433e14063f16dfcb
Para obtener las últimas noticias de política, la URI será:
http://elcomercio.pe/api/news.json?cat=politica&key=2c17325ef5e7f433e14063f16dfcb
Para obtener las 8 últimas noticias.
http://elcomercio.pe/api/news.json?n=8&key=2c17325ef5e7f433e14063f16dfcb
Para obtener las 8 últimas noticias de deportes.
http://elcomercio.pe/api/news.json?cat=deportes&n=8&key=2c17325ef5e7f433e14063f16dfcb
API : Noticias Edición Impresa
La URI estará formada del siguiente modo:
/api/paper.json?date=[fechaEdicion]&key=[keyAcceso]
El parámetro [date] es opcional.
- El formato de [date] es: YYYY-MM-DD
- Si en la petición no se define [date] , entonces el sistema devolverá la imagen y las notas de portada del día actual.
- Si se define [date], el sistema devolverá la imagen y las notas de portada de la fecha especificada.
- La data básica que devuelve el sistema por noticia está compuesta por: imagen, id-nota, titulo-nota, link-nota.
Data Devuelta
El sistema devolverá la data en formato Json. La data es un array multidimensional conformado por una 'Cabecera' y la propia 'Data'. A continuación se detalla:
- INFO
-> [site]: Proveedor de Noticias, El Comercio
-> [type]: Tipo de consulta hecha.
-> [date]: Fecha de Edición.
- DATA
-> [img]: Url imagen de la portada.
-> [notas]
-> nid: Id Nota
- title: Título de la nota en la Web El Comercio.
- url: URL de la nota en la Web El Comercio.
Ejemplos
Para obtener las notas de la edición impresa actual, la URI será:
http://elcomercio.pe/api/paper.json?key=2c17325ef5e7f433e14063f16dfcb
Para obtener las notas de la edición impresa del 14/07/2009, la URI será:
http://elcomercio.pe/api/paper.json?date=2009-07-14&key=2c17325ef5e7f433e14063f16dfcb
API : Obtener data
Usando PHP
Un script en PHP de ejemplo para acceder a las noticias sería del siguiente modo:
$pars = array(
'n' => '10',
'key' => '2c17325ef5e7f433e14063f16dfcb',
);
foreach ($pars as $k => $v):
$enpars[] = urlencode($k).'='.urlencode($v);
endforeach;
$ch = curl_init();
curl_setopt ($ch, CURLOPT_URL, "http://elcomercio.pe/api/news.json?".implode('&', $enpars));
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt ($ch, CURLOPT_CUSTOMREQUEST, "GET");
$resp = curl_exec($ch);
curl_close($ch);
echo $resp;
[NOTA: El 'key' usado en este ejemplo deberá ser reemplazado por su propio key. Este key no es válido.]
La data será devuelta en formato JSON. Para poder visualizarla de modo correcto se debe decodificar la misma, para lo cual existen varios métodos según el lenguaje de programación usado. En el caso de PHP:
$content = json_decode($resp);
Al usar [json_decode($resp)] obtendremos objetos, pero si se prefiere trabajar como array asociativo entonces se debe usar [json_decode($resp, TRUE)]. Se puede revisar más al respecto en la documentación propia de PHP.
Para acceder a la información general sobre la consulta hecha, se debe apuntar a [INFO] y luego al elemento respectivo:
echo 'Sitio: '. $content->info->site; echo 'Tipo de Consulta: '. $content->info->type; echo 'Número de noticias devueltas: '. $content->info->n;
En cuanto a las noticias, se apunta a [DATA] y se recorre cada elemento:
foreach($content->data as $nid=>$noticia): echo 'Id: '. $nid; echo 'Titulo: '. $noticia->title; echo 'Bajada: '. $noticia->extract; echo 'URL: '. $noticia->url; echo 'Fecha: '. $noticia->date; echo 'Timestamp: '. $noticia->timestamp; endforeach;
Usando Python
import urllib2
import simplejson
api_key = "2c17325ef5e7f433e14063f16dfcb"
url = 'http://elcomercio.pe/api/news.json?key=%s' % api_key
req = urllib2.Request(url)
res = simplejson.load(urllib2.urlopen(req),encoding="utf-8")
data = res['data']
for noticia in [data[id] for id in data]:
print noticia['url']
