Tu primera llamada a una API con JavaScript, paso a paso

BLOG

TECH

Programación

Tu primera llamada a una API: consulta el tiempo con JavaScript paso a paso

Por:

Franco Brutti

29 de octubre de 2026

Fecha de Actualización:

29 de octubre de 2026

Una llamada a una API es una petición a una dirección web que, en lugar de una página, devuelve datos. Con fetch y una veintena de líneas de JavaScript puedes pedir la temperatura actual de Madrid a un servicio público y verla en tu navegador. No te registras en ningún sitio, no copias ninguna clave y no instalas nada.

Esto es lo que vas a hacer: abrir la URL de la API a mano, leer lo que devuelve, escribir tu primera página con fetch, comprobar qué pasa cuando algo sale mal y cambiar de ciudad buscándola por su nombre. Todo el código de este tutorial lo probé el 29-10-2026 en Chrome y funciona tal cual.

Si te interesa la teoría de por qué las APIs siguen el estilo REST, la tienes en qué es una API REST y cómo puede disparar tu carrera. Aquí vamos directos a la práctica.

Qué necesitas antes de empezar

Necesitas un navegador actual, un editor de texto cualquiera (el Bloc de notas sirve) y conexión a internet. La API que usamos es Open-Meteo, un servicio meteorológico con una API gratuita para uso no comercial. En las pruebas de hoy no pidió clave ni registro.

Lo que escribas lo vas a guardar en un único fichero, tiempo.html, y lo abrirás con doble clic. Nada de servidores ni de terminal. Si ya has hecho una página con HTML, tienes el nivel de sobra. Y si no, copia el código tal cual: la gracia está en ver cómo se mueven los datos, no en escribir de memoria.

Una cosa sobre las condiciones de uso. Según la página de condiciones de Open-Meteo, la API gratuita es para uso no comercial, con menos de 10.000 llamadas al día, y los datos se publican con licencia CC-BY 4.0. Entre los ejemplos de uso no comercial que cita figura el contenido educativo, que es justo lo que estás haciendo.

Paso 1: abre la API en el navegador, sin código

Antes de programar nada, pega esta dirección en la barra del navegador y pulsa Intro. Verás un bloque de texto con la temperatura y el viento de Madrid ahora mismo. Esa es una llamada a una API: tu navegador pide, el servidor contesta con datos.

https://api.open-meteo.com/v1/forecast?latitude=40.4165&longitude=-3.7026&current=temperature_2m,wind_speed_10m&timezone=Europe%2FMadrid

https://api.open-meteo.com/v1/forecast?latitude=40.4165&longitude=-3.7026&current=temperature_2m,wind_speed_10m&timezone=Europe%2FMadrid

https://api.open-meteo.com/v1/forecast?latitude=40.4165&longitude=-3.7026&current=temperature_2m,wind_speed_10m&timezone=Europe%2FMadrid

La respuesta llega en formato JSON, un texto con pares «nombre: valor» que tanto una persona como un programa pueden leer. Esto es lo que devolvió a las 9:45 del 29-10-2026 (el tuyo tendrá otros números, porque el tiempo cambia):

{
  "latitude": 40.39599,
  "longitude": -3.6793447,
  "generationtime_ms": 0.05614757537841797,
  "utc_offset_seconds": 3600,
  "timezone": "Europe/Madrid",
  "timezone_abbreviation": "GMT+1",
  "elevation": 651.0,
  "current_units": {
    "time": "iso8601",
    "interval": "seconds",
    "temperature_2m": "°C",
    "wind_speed_10m": "km/h"
  },
  "current": {
    "time": "2026-10-29T09:45",
    "interval": 900,
    "temperature_2m": 11.3,
    "wind_speed_10m": 3.1
  }
}

{
  "latitude": 40.39599,
  "longitude": -3.6793447,
  "generationtime_ms": 0.05614757537841797,
  "utc_offset_seconds": 3600,
  "timezone": "Europe/Madrid",
  "timezone_abbreviation": "GMT+1",
  "elevation": 651.0,
  "current_units": {
    "time": "iso8601",
    "interval": "seconds",
    "temperature_2m": "°C",
    "wind_speed_10m": "km/h"
  },
  "current": {
    "time": "2026-10-29T09:45",
    "interval": 900,
    "temperature_2m": 11.3,
    "wind_speed_10m": 3.1
  }
}

{
  "latitude": 40.39599,
  "longitude": -3.6793447,
  "generationtime_ms": 0.05614757537841797,
  "utc_offset_seconds": 3600,
  "timezone": "Europe/Madrid",
  "timezone_abbreviation": "GMT+1",
  "elevation": 651.0,
  "current_units": {
    "time": "iso8601",
    "interval": "seconds",
    "temperature_2m": "°C",
    "wind_speed_10m": "km/h"
  },
  "current": {
    "time": "2026-10-29T09:45",
    "interval": 900,
    "temperature_2m": 11.3,
    "wind_speed_10m": 3.1
  }
}

Fíjate en dos cosas. La temperatura está dentro de current, y su unidad dentro de current_units. Y la latitud que devuelve (40,39599) no es exactamente la que pediste (40,4165): según la documentación, es el centro de la celda de la cuadrícula meteorológica que generó el pronóstico, y puede estar a unos kilómetros de tu punto. No es un error.

Paso 2: entiende qué le estás pidiendo

La dirección tiene una parte fija y varios parámetros después del signo de interrogación. Cada parámetro es una pregunta concreta a la API, y la documentación de Open-Meteo explica todos. Estos son los que usas hoy:

latitude y longitude: las coordenadas del lugar. Son obligatorias. Las de Madrid (40,4165 y -3,7026) las saqué de la propia API de búsqueda de ciudades de Open-Meteo, que usaremos en el paso 5.
current: la lista de variables que quieres «ahora», separadas por comas. Aquí, temperature_2m (temperatura del aire a dos metros del suelo) y wind_speed_10m (viento a diez metros).
timezone: la zona horaria. Acepta cualquier nombre de la base de datos de zonas horarias. La barra de Europe/Madrid se escribe %2F dentro de una URL.

Las unidades por defecto son grados Celsius y km/h; si prefieres otras, hay parámetros como temperature_unit y wind_speed_unit en la documentación. Prueba ahora a cambiar wind_speed_10m por relative_humidity_2m en la barra del navegador y pulsa Intro. Si la respuesta cambia, ya has entendido cómo se «pregunta» a una API.

¿Te está gustando hablar con una API?
En el máster Rock the AI Code, el Proyecto 02 es una app del tiempo que consume una API meteorológica. Descarga el dossier y mira los 8 proyectos.
Descargar el dossier →

Paso 3: tu primera llamada con fetch

El navegador trae una función, fetch, que hace exactamente lo que acabas de hacer a mano: pide una URL y espera la respuesta. Crea un fichero llamado tiempo.html, pega este código y ábrelo con doble clic.

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <title>El tiempo en Madrid</title>
</head>
<body>
  <h1>El tiempo en Madrid</h1>
  <p id="resultado">Consultando…</p>

  <script>
    const url =
      "https://api.open-meteo.com/v1/forecast" +
      "?latitude=40.4165&longitude=-3.7026" +
      "&current=temperature_2m,wind_speed_10m" +
      "&timezone=Europe%2FMadrid";

    async function mostrarTiempo() {
      const salida = document.querySelector("#resultado");
      try {
        const respuesta = await fetch(url);
        if (!respuesta.ok) {
          throw new Error("estado " + respuesta.status);
        }
        const datos = await respuesta.json();
        salida.textContent =
          datos.current.temperature_2m + " " + datos.current_units.temperature_2m +
          ", viento de " + datos.current.wind_speed_10m + " " + datos.current_units.wind_speed_10m;
      } catch (error) {
        salida.textContent = "No se pudo consultar el tiempo (" + error.message + ").";
      }
    }

    mostrarTiempo();
  </script>
</body>
</html>

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <title>El tiempo en Madrid</title>
</head>
<body>
  <h1>El tiempo en Madrid</h1>
  <p id="resultado">Consultando…</p>

  <script>
    const url =
      "https://api.open-meteo.com/v1/forecast" +
      "?latitude=40.4165&longitude=-3.7026" +
      "&current=temperature_2m,wind_speed_10m" +
      "&timezone=Europe%2FMadrid";

    async function mostrarTiempo() {
      const salida = document.querySelector("#resultado");
      try {
        const respuesta = await fetch(url);
        if (!respuesta.ok) {
          throw new Error("estado " + respuesta.status);
        }
        const datos = await respuesta.json();
        salida.textContent =
          datos.current.temperature_2m + " " + datos.current_units.temperature_2m +
          ", viento de " + datos.current.wind_speed_10m + " " + datos.current_units.wind_speed_10m;
      } catch (error) {
        salida.textContent = "No se pudo consultar el tiempo (" + error.message + ").";
      }
    }

    mostrarTiempo();
  </script>
</body>
</html>

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <title>El tiempo en Madrid</title>
</head>
<body>
  <h1>El tiempo en Madrid</h1>
  <p id="resultado">Consultando…</p>

  <script>
    const url =
      "https://api.open-meteo.com/v1/forecast" +
      "?latitude=40.4165&longitude=-3.7026" +
      "&current=temperature_2m,wind_speed_10m" +
      "&timezone=Europe%2FMadrid";

    async function mostrarTiempo() {
      const salida = document.querySelector("#resultado");
      try {
        const respuesta = await fetch(url);
        if (!respuesta.ok) {
          throw new Error("estado " + respuesta.status);
        }
        const datos = await respuesta.json();
        salida.textContent =
          datos.current.temperature_2m + " " + datos.current_units.temperature_2m +
          ", viento de " + datos.current.wind_speed_10m + " " + datos.current_units.wind_speed_10m;
      } catch (error) {
        salida.textContent = "No se pudo consultar el tiempo (" + error.message + ").";
      }
    }

    mostrarTiempo();
  </script>
</body>
</html>

Si todo va bien, la página dirá algo como «11.3 °C, viento de 3.1 km/h». Esa cifra ha viajado desde un servidor meteorológico hasta tu pantalla gracias a código que has pegado tú. Es la mecánica de cualquier app que muestre datos externos: pedir, esperar, leer, pintar.

Paso 4: qué hace cada línea

Las líneas importantes son pocas, y conviene entenderlas una a una porque las vas a reescribir cientos de veces.

const url = ...: guarda la dirección en una variable. Está partida en trozos con + solo para que se lea mejor.
async function y await: fetch tarda un poco en recibir respuesta. await le dice a JavaScript que espere ese resultado antes de seguir con la línea siguiente, y para usarlo la función tiene que ser async.
respuesta.ok: vale true si el estado HTTP está entre 200 y 299, según MDN.
respuesta.json(): convierte el texto de la respuesta en un objeto de JavaScript que puedes recorrer con puntos, como datos.current.temperature_2m.
try y catch: si algo falla, el programa salta al catch y escribe un mensaje en lugar de quedarse mudo.

Hay un detalle de fetch que despista a casi todo el mundo al empezar. Según MDN, la promesa que devuelve no se rechaza por un error HTTP como un 404 o un 500: se resuelve con ok en false, y solo se rechaza ante un fallo de red o si algo impidió completar la petición. Por eso el código comprueba respuesta.ok a mano. Sin esa línea, un 404 llegaría a json() como si fuera una respuesta buena.

Paso 5: provoca un error a propósito

Equivocarte con calma es la mejor forma de aprender, así que rómpelo tú. Cambia latitude=40.4165 por latitude=999 y recarga la página. Verás «No se pudo consultar el tiempo (estado 400)».

Según la documentación de Open-Meteo, cuando un parámetro está mal especificado la API devuelve un objeto JSON con error y reason y un estado HTTP 400. Ese reason explica el motivo, así que puedes enseñárselo a quien use tu página. Sustituye esta línea dentro del if:

throw new Error("estado " + respuesta.status);

throw new Error("estado " + respuesta.status);

throw new Error("estado " + respuesta.status);

por estas dos:

const fallo = await respuesta.json();
throw new Error(fallo.reason);

const fallo = await respuesta.json();
throw new Error(fallo.reason);

const fallo = await respuesta.json();
throw new Error(fallo.reason);

Con la latitud 999 la página mostrará: «No se pudo consultar el tiempo (Latitude must be in range of -90 to 90°. Given: 999.0.)». Es inglés porque lo escribe la API, pero ya sabes qué parámetro corregir. Vuelve a poner 40.4165 y recupera tu temperatura.

Hay un tercer tipo de fallo: que no haya conexión. Entonces fetch se rechaza con un TypeError y el catch lo recoge igual. Lo comprobé pidiendo una dirección que no existe.

Del primer error al primer proyecto
Pide el dossier de Rock the AI Code y revisa qué proyectos construirás, del frontend al despliegue.
Descargar el dossier →

Paso 6: cambia de ciudad buscándola por su nombre

Las coordenadas de memoria no escalan. Open-Meteo tiene una segunda API, la de geocodificación, que convierte el nombre de una ciudad en latitud, longitud y zona horaria. Su documentación está en Open-Meteo Geocoding API: se llama con name (el nombre), count (cuántos resultados) y language.

Sustituye todo el contenido de tu <script> por este. Tiene dos funciones: una busca la ciudad y otra pide el tiempo con lo que la primera encontró.

async function buscarCiudad(nombre) {
  const url =
    "https://geocoding-api.open-meteo.com/v1/search" +
    "?name=" + encodeURIComponent(nombre) +
    "&count=1&language=es";

  const respuesta = await fetch(url);
  if (!respuesta.ok) {
    throw new Error("La búsqueda falló con el estado " + respuesta.status);
  }

  const datos = await respuesta.json();
  if (!datos.results) {
    throw new Error("No encuentro ninguna ciudad llamada " + nombre);
  }

  const { name, latitude, longitude, timezone } = datos.results[0];
  return { name, latitude, longitude, timezone };
}

async function tiempoDe(nombre) {
  const ciudad = await buscarCiudad(nombre);

  const url =
    "https://api.open-meteo.com/v1/forecast" +
    "?latitude=" + ciudad.latitude +
    "&longitude=" + ciudad.longitude +
    "&current=temperature_2m,wind_speed_10m" +
    "&timezone=" + encodeURIComponent(ciudad.timezone);

  const respuesta = await fetch(url);
  if (!respuesta.ok) {
    const fallo = await respuesta.json();
    throw new Error(fallo.reason);
  }

  const datos = await respuesta.json();
  return ciudad.name + ": " + datos.current.temperature_2m + " " + datos.current_units.temperature_2m;
}

const salida = document.querySelector("#resultado");
tiempoDe("Sevilla")
  .then((texto) => { salida.textContent = texto; })
  .catch((error) => { salida.textContent = error.message; });

async function buscarCiudad(nombre) {
  const url =
    "https://geocoding-api.open-meteo.com/v1/search" +
    "?name=" + encodeURIComponent(nombre) +
    "&count=1&language=es";

  const respuesta = await fetch(url);
  if (!respuesta.ok) {
    throw new Error("La búsqueda falló con el estado " + respuesta.status);
  }

  const datos = await respuesta.json();
  if (!datos.results) {
    throw new Error("No encuentro ninguna ciudad llamada " + nombre);
  }

  const { name, latitude, longitude, timezone } = datos.results[0];
  return { name, latitude, longitude, timezone };
}

async function tiempoDe(nombre) {
  const ciudad = await buscarCiudad(nombre);

  const url =
    "https://api.open-meteo.com/v1/forecast" +
    "?latitude=" + ciudad.latitude +
    "&longitude=" + ciudad.longitude +
    "&current=temperature_2m,wind_speed_10m" +
    "&timezone=" + encodeURIComponent(ciudad.timezone);

  const respuesta = await fetch(url);
  if (!respuesta.ok) {
    const fallo = await respuesta.json();
    throw new Error(fallo.reason);
  }

  const datos = await respuesta.json();
  return ciudad.name + ": " + datos.current.temperature_2m + " " + datos.current_units.temperature_2m;
}

const salida = document.querySelector("#resultado");
tiempoDe("Sevilla")
  .then((texto) => { salida.textContent = texto; })
  .catch((error) => { salida.textContent = error.message; });

async function buscarCiudad(nombre) {
  const url =
    "https://geocoding-api.open-meteo.com/v1/search" +
    "?name=" + encodeURIComponent(nombre) +
    "&count=1&language=es";

  const respuesta = await fetch(url);
  if (!respuesta.ok) {
    throw new Error("La búsqueda falló con el estado " + respuesta.status);
  }

  const datos = await respuesta.json();
  if (!datos.results) {
    throw new Error("No encuentro ninguna ciudad llamada " + nombre);
  }

  const { name, latitude, longitude, timezone } = datos.results[0];
  return { name, latitude, longitude, timezone };
}

async function tiempoDe(nombre) {
  const ciudad = await buscarCiudad(nombre);

  const url =
    "https://api.open-meteo.com/v1/forecast" +
    "?latitude=" + ciudad.latitude +
    "&longitude=" + ciudad.longitude +
    "&current=temperature_2m,wind_speed_10m" +
    "&timezone=" + encodeURIComponent(ciudad.timezone);

  const respuesta = await fetch(url);
  if (!respuesta.ok) {
    const fallo = await respuesta.json();
    throw new Error(fallo.reason);
  }

  const datos = await respuesta.json();
  return ciudad.name + ": " + datos.current.temperature_2m + " " + datos.current_units.temperature_2m;
}

const salida = document.querySelector("#resultado");
tiempoDe("Sevilla")
  .then((texto) => { salida.textContent = texto; })
  .catch((error) => { salida.textContent = error.message; });

Recarga y verás «Sevilla: 16 °C» (u otra cifra, según cuándo lo pruebes). Cambia "Sevilla" por tu ciudad y pulsa de nuevo. Dos detalles útiles. encodeURIComponent protege los nombres con espacios o tildes para que viajen bien dentro de la URL. Y la comprobación de datos.results existe porque, cuando la búsqueda no encuentra nada, la respuesta llega sin ese campo: lo vi pidiendo una ciudad inventada, y el mensaje de error lo gestiona.

Qué acabas de aprender (y por dónde seguir)

Con esos dos ficheros has practicado el esqueleto de casi cualquier integración con una API: construir la URL, llamar con fetch, comprobar ok, leer el JSON y gestionar el error. Cambia Open-Meteo por otro servicio y los pasos son los mismos. Solo cambian los nombres de los parámetros y la forma del JSON, que se aprende leyendo la documentación, como has hecho hoy.

Para seguir, tienes tres ideas sencillas. Añade weather_code a current y traduce el número a texto con la tabla de códigos de la documentación (0 es «cielo despejado», 3 «cubierto»). Pide varios días con el parámetro daily. Y si quieres ver las respuestas sin escribir código, la herramienta que se usa para probar APIs la explicamos en todo sobre Postman.

De la llamada a una app completa

En el máster Rock the AI Code de The Power, el Proyecto 02 se llama «App del tiempo», y su ficha lo resume así: «Interfaz, datos externos y lógica guiada por IA. Consume una API meteorológica, modela estados de interfaz y acelera la implementación con IA» (consultado el 29-10-2026 en la ficha del máster). Lo que has hecho hoy es el primer paso de ese tipo de proyecto: ahí lo amplías con una interfaz completa y con apoyo de IA.

La misma ficha indica que el máster tiene 8 proyectos reales, que cada uno sube el nivel del anterior y que «no necesitas conocimientos previos». Entre lo que dice que podrás construir está el frontend con «HTML, CSS, Tailwind, JavaScript y React, conectadas a APIs externas y a tu propio backend». Si esta llamada te ha dejado con ganas de más, el dossier te enseña los proyectos y el temario completo.

Tu siguiente paso: construir tu app del tiempo
Descarga el dossier de Rock the AI Code y descubre los 8 proyectos y el syllabus completo.
Descargar el dossier →

Preguntas frecuentes sobre tu primera llamada a una API

¿Necesito una clave o registrarme para usar Open-Meteo?

En las pruebas del 29-10-2026 todas las llamadas funcionaron sin clave ni registro. Si algún día usas una API que sí pida clave, no la pegues en código que publiques en internet: cualquiera que abra la página podría leerla.

¿Puedo usar este código en un proyecto de mi empresa?

Depende del uso. La API gratuita de Open-Meteo es solo para uso no comercial: una web o app con suscripciones o publicidad cuenta como comercial, según sus condiciones. Para un ejercicio, un portfolio personal o contenido educativo, encaja. Si tu proyecto es comercial, tienen planes de pago.

¿Qué es una API REST y qué relación tiene con esto?

Open-Meteo se consulta con peticiones a direcciones web y responde en JSON, la misma mecánica que acabas de practicar. Si quieres la definición de REST y la comparación con otros estilos, está en el artículo sobre qué es una API REST.

¿Por qué fetch no falla cuando la API devuelve un 404?

Porque fetch solo rechaza la promesa ante fallos de red; un 404 o un 500 se consideran respuestas válidas con ok en false, tal como explica MDN. Por eso se comprueba respuesta.ok antes de leer el JSON.

Comparte este artículo

LinkedIn WhatsApp Facebook X

Categorías

Destacados

Programación

Transformación Digital

¿Buscas algo en concreto?

Másters