DIA 18 / 2015

Receta: Trabajando con APIs (El tiempo en tu web)

Nunca antes había sido tan fácil conectar nuestros sitios web o aplicaciones online con servicios de terceros gracias al auge de las APIs. En este mini tutorial echamos un vistazo completo al proceso de obtener datos de una API de información meteorológica: desde la conexión al procesado de los datos y su presentación en pantalla.


Nunca antes había sido tan fácil conectar nuestros sitios web o aplicaciones online con servicios de terceros gracias al auge de las APIs. Estos sistemas permiten que nuestros productos se entiendan con otros, que intercambien información, que hagan cosas. Los resultados que podemos obtener son increíbles y las opciones que tenemos para ampliar las funcionalidades de nuestros sitios son casi infinitas.

Gracias a servicios como, por ejemplo, Mandrill y su API, podemos desarrollar sistemas de envío de correos de forma robusta y estable sin preocuparnos de la carga de nuestro servidor. Con la API de Xero podemos llevar la consulta de las finanzas de nuestra empresa a una intranet. Spotify nos permite consultar su catálogo, en Last.fm podemos ver tendencias musicales, con la API de Instagram podemos mostrar fotos de nuestra ciudad en la web de turismo, podemos hacer una app de reconocimiento facial, de escaneado de documentos con OCR… Adentrarse en el mundo de las APIs es maravilloso por todo lo que uno descubre que, de repente, puede hacer (en esta misma edición de Octuweb Ricardo Prieto nos habla del interesante futuro de los temas de WordPress gracias al desarrollo de su REST API).

En este mini tutorial vamos a echar un vistazo al proceso completo de obtener datos de una API de un servicio externo (información meteorológica del lugar que indiquemos en tiempo real), procesar la información y mostrarla en nuestro sitio web. Imaginemos que estamos haciendo un sitio para un hotel en una estación de esquí o en una costa famosa por sus olas y el surf. Queremos mostrar a todos nuestros visitantes las buenas condiciones que se dan en la zona y que vengan a visitarnos (y conseguir una reserva, claro). ¿Preparados? Vamos a cocinar.

api-tiempo-ejemplo

Ingredientes:

  • Una API interesante de la que obtener los datos
  • Una pizca de JSON (las APIs suelen darnos la información en este sabor)
  • Un poco de AJAX para cargar ese JSON
  • JQuery (o JavaScript) para manipular la información y pintar en pantalla
  • HTML y CSS
  • La estupenda fuente Weather Icons para mostrar unos bonitos iconos de soles, nubes y rayos

Llamando a la API

Vamos a usar el servicio que ofrece Open Weather Map que tienen una API que podemos usar gratis si no tenemos más de 50.000 llamadas al día.

Lo primero que necesitamos es una clave para poder usar la API. Para ello nos registramos en la página:

api-tiempo-openweather-register

Creamos un objeto nuevo vacío que contendrá la lógica de nuestra pequeña aplicación:

//creamos el objeto app

var app = {};

//nuestra api key

app.apikey = "3e721e227b5c28d8ff5691e4fff1c36";

//en la URL indicamos la ciudad, en este ejemplo q=Malaga

app.url = "http://api.openweathermap.org/data/2.5/weather?q=Malaga&APPID=" + app.apikey + "&units=metric";

Definimos en dos variables dentro de app la clave (app.apikey) que nos ha dado Open Weather Map y la URL a la que debemos llamar para traernos la información (app.url).

Ya tenemos los ingredientes necesarios para empezar a cocinar. Vamos a pedirle a la API que nos dé los datos del tiempo que hace en Málaga en este momento. Hacemos la llamada con $.ajax():

app.cargaDatos = function(){

$.ajax({

url: app.url,

success: function( data ) {

//guardamos en la variable datos dentro del objeto app toda la información “en bruto”

app.datos = data;


//a continuación lanzamos la función procesaDatos que se encarga del manipulado de los datos

app.procesaDatos();

},

//algo no ha ido bien, por simplificar el ejemplo no vamos a analizar los tipos de error, solo mostramos un mensaje

//en el mundo real analizaríamos el error que nos devuelve la API para actuar de una manera u otra

error: function(){

alert("¡Ups! No puedo obtener información de la API");

}

});

}
api-tiempo-consola
Vista de la consola de Chrome con los datos cargados “en bruto” en la variable app.datos

Almacenando y manipulando los datos

Una vez que hemos cargado la URL, almacenamos la información en bruto en la variable app.datos. Entonces llamamos a la función procesaDatos que se encargará de manejar los datos y seleccionar aquellos elementos que nos interesen y enviárselos a otra función para que los “pinte” en el navegador.

Si apuntamos con nuestro navegador a esta URL veremos que la información viene en formato JSON:

{

"coord":{

"lon":-4.42,

"lat":36.72

},

"weather":[

{

"id":804,

"main":"Clouds",

"description":"overcast clouds",

"icon":"04d"

}

],

"base":"stations",

"main":{

"temp":50,

"pressure":1022,

"humidity":87,

"temp_min":50,

"temp_max":50

},

"visibility":6000,

"wind":{

"speed":2.16

},

"clouds":{

"all":90

},

"dt":1445250000,

"sys":{

"type":1,

"id":4886,

"message":0.0092,

"country":"ES",

"sunrise":1445236124,

"sunset":1445276157

},

"id":2514256,

"name":"Malaga",

"cod":200

}

De todos estos valores solo utilizaremos en nuestro sitio los de temperatura, el nombre de la condición atmosférica y su correspondiente icono.

La función para extraer los valores que necesitamos es bastante sencilla:

app.procesaDatos = function(){

//guardamos los datos por separado en variables

app.condicionNombre = app.datos.weather[0].main;

app.temperatura = app.datos.main.temp, 10;


var condicionIcono = app.datos.weather[0].icon;

//obtenemos el icono (una clase) para el código que indicamos

app.icono = app.obtenIcono( condicionIcono );


//vamos al siguiente paso en el proceso: el “pintado” de los elementos en pantalla

app.muestra();

}

En esta función asignamos los valores que vamos a mostrar en nuestra mini-aplicación:

  • condicionNombre: la condición atmosférica (clouds, rain, sí, la API está en inglés)
  • temperatura: (tipo 12.2º)
  • condicionIcono: la API nos da un código (‘01d’, ‘04n’) que hace referencia a un archivo .png con un icono que muestra la condición atmosférica. Nosotros vamos a usar una fuente web en lugar de estos PNG pero nos vamos a guiar por esta nomenclatura.
  • icono: para asignar valor a esta variable vamos a llamar a la función obtenIcono()

obtenIcono() es una función que se encarga básicamente de “traducir” el código que nos da la API en el nombre de una clase de la fuente web que vamos a utilizar para mostrar un bonito icono.

app.obtenIcono = function( weatherIcon ) {

var icon;

switch( weatherIcon ){

case "01d":

case "01n":

icon = "wi-day-sunny";

break;

case "02d":

case "02n":

icon = "wi-day-cloudy";

break;


//muchos más casos

}

return icon;

}

Nada especial aquí, para cada código obtenemos una clase de la fuente Weather Icons. Si la API nos indica, por ejemplo, 09d (d es de día, n de noche) nuestra función nos devuelve wi-rain. El listado completo de iconos está aquí:

La última línea de la función procesaDatos llama a la otra función app.muestra() que se encargará de modificar el DOM para mostrar la información.

Mostrando la información

Ahora que ya tenemos todos los datos que necesitamos y que los hemos manipulado y transformado podemos pasar a mostrar en pantalla la información del tiempo.

Lo primero que hacemos es trabajar el HTML de nuestra aplicación web:

<section class="section__main">
    <div class="section__content">
        <h1>Conectando con la API de tiempo</h1>
        <h2>El tiempo en Málaga</h2>
        <div class="weather__block" id="js_w_temp"></div>
        <div class="weather__block" id="js_w_icon"></div>
    </div>
</section>

Tenemos una sección en la que vamos a mostrar la temperatura y el icono del tiempo. Cada elemento irá en un bloque con la clase weather__block. Como necesitamos modificar cada bloque por separado les asignamos una id a cada uno: js_w_temp para el bloque de la temperatura y js_w_icon para el bloque del icono.

Ahora que tenemos definidos los espacios contenedores vacíos en los que mostraremos la información, toca escribir la función app.muestra():

app.muestra = function(){

$('#js_w_temp').append("&lt;p class='weather_temperature'&gt;" + app.temperatura + "º&lt;/p&gt;");

$('#js_w_icon').append(" &lt;i class='wi " + app.icono + "'&gt;&lt;/i&gt;");

$('#js_w_icon').append("&lt;p class='weather_name'&gt;" + app.condicionNombre.toUpperCase() + "&lt;/p&gt;");

}

Esta función de pintado fue lanzada por processData() una vez que terminó de manipular todos los datos. Lo que hacemos aquí es añadir esos trozos de HTML en los elementos marcados con los ids y los completamos con la información obtenida de la API.

Usamos el método append de JQuery para insertar contenido en los elementos #js_w_temp y #js_w_icon. En el primero simplemente mostramos la temperatura (app.temperatura) y en el segundo mostramos el icono con la clase wi, añadiendo además la clase con la condición atmosférica adecuada. Tras el icono añadimos un elemento de párrafo con el tiempo en texto. Hay otras muchas funciones de JQuery para manipular el DOM (html, innerHTML, replaceWith…). Es muy interesante estudiar motores de renderizado como Mustache o Handlebars (The top 5 JavaScript templating engines).

Con esto hemos llegado al final del proceso. Puedes echar un vistazo al código en CodePen (la fuente de icono no se renderiza en CodePen :( por políticas de seguridad).

Acabando

Hemos separado todo el proceso en diferentes pasos con funciones muy esenciales y concretas. Este ha sido un caso muy sencillo. Podríamos haberlo hecho todo con menos pasos, con menos funciones, pero así podremos escalar más fácilmente nuestra aplicación en el futuro, añadir nuevas funcionalidades, podremos crear tests unitarios y, en definitiva, estamos siguiendo una de las “mejores prácticas” de JavaScript (y de cualquier lenguaje de programación).

Con el auge de las APIs y el protagonismo cada vez mayor de lenguajes del lado del cliente como JavaScript (y los miles de frameworks alucinantes que aparecen regularmente como Angular o React) estamos ante una era dorada del front-end. Espero que hayas disfrutado este mini-tutorial que es solo un ejemplo, una pequeña muestra de la punta del iceberg.

Hay un universo enorme aquí al lado, justo en tu navegador.

Ernesto Jiménez
Ernesto Jiménez

Ernesto Jiménez es un diseñador especializado en el diseño y desarrollo de sitios web.
Ha tenido la enorme suerte de trabajar para empresas como Red Bull, Microsoft España, Antonio Herráiz Publicidad y Diseño, Diario Sur y otras.
Licenciado en Ciencias de la Comunicación y Máster en Diseño Gráfico en la Universidad de Málaga.