|
API_1_0
Especificación de la primera versión del API
(-- API_1_0 | LlaveAPI | PreguntasFrecuentes Grupo de Discusión --) Nota : Tenemos un listado de Problemas por resolver. Estamos trabajando para resolverlos. API eltiempo.comEl Tiempo ha puesto a disposición de los desarrolladores interesados un API para consultar los contenidos del portal. En estos momentos estamos en pruebas de la primera versión. Hemos creado una página para preguntas frecuentes y un grupo de discusión. VersiónEn este documento se describe la versión 1.0 del API. ObservacionesEn la página Ejemplos en JavaScript se describe el uso de JSON y de JSONP. En esta página se describirán únicamente las respuestas en XML. Las respuestas en JSON son equivalentes. Por favor escribir al grupo de discusión si hace falta alguna aclaración. Para seleccionar el formato de la respuesta deseada se usa el formato como extensión. Si se quiere usar el formato JSON para consultar el artículo CMS-12345 se usa: Y si se quiere obtener la misma información en formato XML se usa: En la página JSON Pretty Printing Demo hay un script que es util para visualizar JSON. Llave para el uso del APIPara el uso del API se requiere una llave. La documentación completa para el uso de las llaves la puede encontrar en LlaveAPI. La llave obtenida debe ser pasada como parámetro en la petición. Si la llave fuese FOOBAR, la petición sería: EjemplosPara el impaciente¿Quiere ver los datos rápidamente? De acuerdo. Acá están. En XML y JSON: Artículos más votados el 4 de Febrero:
Artículos con más comentarios el 4 de Febrero: Información detallada sobre un artículo: Los 6 comentarios padres más recientes de un artículo. La respuesta puede contener más de 6 comentarios (al incluir comentarios hijos). Programas
Pronto tendremos ejemplos disponibles para más lenguajes. Recursos disponiblesArtículoPara un artículo es posible conocer la información detallada y los comentarios. Para todos los recursos que se pueden consultar de un artículo existen los siguientes elementos comunes en la URI: {portal} {identificador} y {formato}. Portales disponibles:
Identificador:
Formatos disponibles:
Recurso : Información detallada del artículoURI1.0/{portal}/articulos/{identificador}.{formato} Parámetros
RespuestaSi el formato es XML se entregará un archivo con sólo una entrada. El archivo estará en formato Atom.
Un ejemplo de la etiqueta '''eltiempo:actividad''': <eltiempo:actividad visitas="1516" comentarios="70" recomendaciones="10" votos="5"/> Recurso: Comentarios del artículoHay dos tipos de comentarios:
Los comentarios en el recurso se enumeran teniendo en cuenta el índice de los comentarios padres. URI
Un ejemplo: Parámetros
Todos los comentrios hijos de un comentario padre se incluyen en la misma respuesta. Hay un máximo número de hijos a retornar, pero este número no es pequeño. RespuestaSi el formato es XML se entregará un listado de comentarios en formato Atom. Para cada comentario se entregarán los siguientes datos:
En la respuesta se incluye información sobre esta misma. Ejemplo: <eltiempo:comentarios-disponibles>65</eltiempo:comentarios-disponibles> <eltiempo:resultado-indice-inicio>0</eltiempo:resultado-indice-inicio> <eltiempo:resultado-padres>6</eltiempo:resultado-padres> <eltiempo:resultado-hijos>1</eltiempo:resultado-hijos>
EstadísticasArtículos más visitados, más votados, más recomendados y con más comentarios. URI1.0/{portal}/estadisticas/{estadistica}.{formato} Portales disponibles:
Estadísticas disponibles:
Formatos disponibles:
Parámetros
RespuestaSi el formato es XML la respuesta se entrega en un archivo con formato Atom con hasta 20 entradas. Cada entrada (atom:entry) contendrá:
Una entrada de ejemplo: <entry>
<id>tag:api.eltiempo.com,2008:/eltiempo/articulos/CMS-3942445</id>
<title><![CDATA[Universidades denuncian proliferacion de por bares y tiendas en sus inmediaciones]]></title>
<updated>2008-02-02T01:03:03-05:00</updated>
<link href="http://beta.eltiempo.com/archivo/documento/CMS-3942445" rel="alternate"/>
<summary><![CDATA[Y esto sucede, pese a que el Codigo de Policia de Bogota prohibe el funcionamiento de ese tipo de establecimientos a menos de 200 metros de los centros educativos. ]]></summary>
</entry>Tags - Nube del díaListado de etiquetas(tags) asociados a las noticias más leídas del día actual. URI1.0/{portal}/tags/actividad.{formato} Portales disponibles:
Formatos disponibles:
RespuestaSi el formato es XML la respuesta es un listado de cada uno de los tags y un índice (entre 1 y 100) que indica su popularidad. Un número mayor indica más popularidad. <?xml version="1.0" encoding="utf-8"?> <tags> <tag polularidad="100">CAMPUS PARTY</tag> <tag popularidad="70">EUROCOPA</tag> <tag popularidad="60">MELISSA</tag> </tags> SeccionesListado de las secciones de los artículos. URI1.0/{portal}/secciones.{formato} Portales disponibles:
Formatos disponibles:
Parámetros
RespuestaSi el formato es XML la respuesta se entrega en un archivo con un elemento atom:categories. Cada entrada (atom:category) contendrá:
Por ejemplo, <app:categories scheme="http://api.eltiempo.com/1.0/eltiempo/secciones.xml"> <atom:category term="defensor-del-lector" label="Defensor del lector" xml:lang="es-CO"/> <atom:category term="deportes" label="Deportes" xml:lang="es-CO"/> <atom:category term="economia" label="Economía" xml:lang="es-CO"/> </app:categories> BuscadorListado de artículos que se pueden consultar con diferentes criterios. URI1.0/{portal}/articulos.{formato} Portales disponibles:
Formatos disponibles:
Parámetros
RespuestaSi el formato es XML la respuesta se entrega en un archivo con formato Atom con hasta 20 entradas. Cada entrada (atom:entry) contendrá:
Una entrada de ejemplo sería igual a las de los demás feeds: <entry> <id>tag:api.eltiempo.com,2007:/eltiempo/articulos/MAM-2649432</id> <title>40 Años De Les Luthiers</title> <updated>2007-09-10T00:00:00-05:00</updated> <link href="http://beta.eltiempo.com/archivo/documento/MAM-2649432" rel="alternate" type="text/html"/> <link href="/1.0/eltiempo/articulos/-2649432.json" rel="alternate" type="text/json"/> <link href="/1.0/eltiempo/articulos/-2649432.xml" rel="alternate" type="application/atom+xml"/> <summary>Todo empezó como una broma estudiantil. Los coros universitarios eran uno de los ingredientes de moda de la cultura latinoamericana en los años 60 (el de la Universidad de los Andes ganó varios certámenes internacionales). </summary> <category term="editorial-opinion"/> </entry> Recursos que estarán disponibles prontoMuy pronto estaremos publicando más recursos para consultar. Escribimos el listado para que pueda pensar en aplicaciones que los usen, antes de que estén publicados. Noticias por tagActualmente está disponible el listado de tags más activos en el día (nube del día), y para que sea realmente útil se podrá obtener un listado de noticias especificando la etiquetada (tag). Información básica del Perfil del usuarioIncluyendo los comentarios publicados recientemente. Gracias por la sugerencia :-) |
Sign in to add a comment
Ok... pensaré en algo a ver si me animo.
Bueno, pues la API esta muy simple pero veremos que podemos hacer con esto!
Hay posibilidad de sacar un listado de los últimos artículos? (depronto únicamente sus identificadores). Se podrá utilizando los lectores RSS que tiene el sitio?
laneros: Con los feeds actuales se podría, pero tendría que hacer algo adicional para crear los identificadores (utilizar el prefijo 'CMS-'). Con la integración del buscador sería mucho más fácil y este momento estamos terminando las pruebas. Esperamos que eso esté listo hoy en la tarde para que lo puedan comenzar a utilizar.
navickator: Ahora estamos trabajando en los recursos que están pendientes (comentarios, buscador y tags). Si cree que sería útil obtener algo adicional, por favor envíe un mensaje a la lista de discusión y revisamos qué podemos hacer.
Porque solo 20 entradas para los comentarios??? Si es necesario agreguen un mecanismo de paginado porque me parece importante que se puedan acceder a todos los comentarios.
Gracias
villegas2000: Eso lo estoy haciendo en el momento... Se van a paginar, de la siguiente forma: inicio = numero, cantidad = numero. Cantidad es más una sugerencia que una orden (para que El Tiempo pueda cambiar el número máximo que comentarios que se retornan en una petición), así que toca verificar el rango retornado en la respuesta. Voy a editar eso en la Wiki -- Nelson.
Buenos días. Sería posible que en la entrada de cada artículo, aparte del summary, se pueda solicitar el contenido completo del artículo? o por lo menos utilizar un parámetro opcional para cuando quiera obtener el contenido del artículo. Gracias
villegas2000: Por el momento no se puede descargar el contenido completo del artículo (por intermedio del API). Los permakinks serán enlaces al archivo. Ahora mismo algunos están retornando 404, pero eso cambiará cuando la versión beta de El Tiempo pase a ser la vesion a producción. (Entiendo que esto será muy pronto). Puse esta respuesta en la página PreguntasFrecuentes. -- Nelson.
villegas2000: Por el momento no se puede descargar el contenido completo del artículo (por intermedio del API). Los permakinks serán enlaces al archivo. Ahora mismo algunos están retornando 404, pero eso cambiará cuando la versión beta de El Tiempo pase a ser la vesion a producción. (Entiendo que esto será muy pronto). Puse esta respuesta en la página PreguntasFrecuentes. -- Nelson.
Nelson, creo que haría mucha falta tener algún recurso para consultar las últimas 20 noticias publicadas. Serían las últimas 20 noticias publicadas entre todas las categorías. Agradecería que nos brindadas este recurso.
Gracias
villegas 2000: Juan Manuel (mancai.eltiempo) tocó el tema en el comentario anterior (en una respuesta a laneros). El está trabajando en eso y creo que el Lunes puede estar funcionando. Yo ya lo vi funcionando en pruebas y eso es exactamente lo que necesitan (De hecho el buscador permite hacer más cosas). -- Nelson.-
Sí. ES importante poder contar con las últimas 20 entradas, aunque en estos momentos se puede hacer por medio del RSS, pero lo ideal sería por medio de un API como los que implementaron.
hola! ehhhh bueno, vi que los cupos para campus-party ya están llenos... si quiero participar, pero no voy al campus Party... igual podría participar si mi sitio está en un servidor público en internet???
gracias!! CHao!
olucim: Hola, por favor ponte en contacto con nosotros al correo electrónico (api -arroba- eltiempo.com).
Es posible obtener las imágenes asociadas a cada artículo (el enlace, por supuesto)?
manuel.he: Por el momento no está considerado el enlace a las imágenes.
HOla! ¿Es normal que los links que da como respuesta el (servicio Buscador de este API) buscador no sean válidos? tengo ejemplos: si a alguien le sucede lo mismo:
http://beta.eltiempo.com/archivo/documento/MAM-4226873 http://beta.eltiempo.com/archivo/documento/MAM-4222803
Gracias!
olucim: Sí. A todos nos pasa en ocasiones. Ver: http://code.google.com/p/eltiempo-api/issues/detail?id=1
Hemos adicionado un enlace al listado de problemas conocidos en los que estamos trabajando (En el listado de preguntas frecuentes y en esta página. Gracias por el reporte.
Veo que dicen que muy pronto estara disponible 'La Información básica del Perfil del usuario', incluyendo los comentarios. Estara disponible tambien el voto que una persona haya hecho para cierto articulo?? Eso es importante si se quieren hacer recomendaciones por usuarios tal como ustedes mencionan en las ideas de la pagina principal del API.
Gracias.
viajandoenbus: Los votos son privados...
devnullexists: que vaina, entonces no pongan a Amazon como ejemplo para un sistema de recomendacion, que seria muy interesante hacerlo, pero sin saber lo que le gusta al usuario es supremamente dificil. Gracias
viajandoenbus: ¿Es esta la única forma de saber lo que le gusta al usuario? No puedo comentar mucho más sobre el tema mientras el reto sigue pendiente. Creo que estaría mal que El Tiempo revele esa información que muchos consideran privada. El Tiempo garantiza que no divulgará la información privada que los usuarios aportan.
devnullexists: Pues yo habia pensado implementar un Filtro Colaborativo, como los que usa Amazon, Last.fm, Netflix, o alguno de esos que se basan en las calificaciones de usuarios. Quiza no sea la unica forma, pero de seguro es la mas rapida y menos engorrosa si se tuviera esa informacion.
http://en.wikipedia.org/wiki/Collaborative_filtering
viajandoenbus: Estoy de acuerdo, sería más fácil filtrar de esa forma. No obstante, es más delicado cuando se trata de calificaciones sobre opiniones. Es mucho menos impersonal.
nelsoneci: Si, igual yo entiendo las politicas de El Tiempo. De cualquier forma con la informacion que provee el API de seguro se pueden hacer cosas muy interesantes, y quiza descubrir cosas muy buenas. Tengo otra duda, el servidor que atiende las peticiones del API es el mismo que atiende las de la pagina?, hay algun numero limitado de peticiones por minuto por cada llave o alguna politica por el estilo? Muchas gracias por las respuestas y estare pendiente.
viajandoenbus: En el momento no estamos aplicando límites y más bien estamos mirando los patrones de uso. A futuro las aplicaciones deberían prepararse para manejar un status de respuesta 503, pero por favor no se preocupe por eso ahora, ya que la prioridad es mantener las cosas simples para que no tengan problemas trabajando para los retos. Lo más probable es que a futuro se limiten peticiones por IP, pero no será un límite pequeño. Es mejor no pensar mucho en esto ahora...
Saludos, estoy teniendo problemas con el acceso a los tags con xml, algunas veces me envia un archivo vacio de tags, mientras el json parece funcionar mejor
hola!! hay algunos archivos que ya no se encuentran en el servidor del api...
gracias!
Hola, hace algunos meses hice un buscador de Blogs y Noticias (www.meaviso.com) e indexo obviamente al eltiempo.com. pero para ello uso los feeds normales de los canales y hasta la fecha no he tenido problemas. pero es muy tentador poder usar propios canales xml. claro que son varios canales aca se ve uno y tambien tienen salida rss 2.0 http://www.meaviso.com/wordpress/authors/1394047/