100 Días de Código en Python — Día 33: APIs, endpoints y parámetros — el Notificador de la ISS

🎯 Objetivo de aprendizaje#

Explicar qué es una API y por qué los programas la necesitan para obtener datos de otros sistemas.

📖 Explicación conceptual#

Muchos sitios web tienen datos valiosos: el pronóstico del clima, el precio de las criptomonedas, las estadísticas de los jugadores de baloncesto. ¿Cómo los usamos en nuestros programas?

Una API es un conjunto de comandos, funciones, protocolos y objetos que los programadores pueden usar para crear software o interactuar con un sistema externo. Funciona como una barrera con reglas: si tu petición cumple las reglas de la API, el sistema te responde con los datos; si no, la rechaza.

La analogía del restaurante (del curso):

Retos adicionales (creados para esta adaptación)#

• 🟢 Reto 1: menciona tres aplicaciones de tu celular que probablemente usan una API (por ejemplo, una aplicación del clima). ¿Qué datos pedirían?
• 🟡 Reto 2: explica la analogía del restaurante con otra situación de tu colegio (por ejemplo, la secretaría académica y los certificados de notas).
• 🟠 Reto 3: ¿por qué una empresa querría ofrecer una API pública y gratuita? ¿Y por qué otra no querría?
• 🔴 Reto 4: investiga si alguna entidad colombiana ofrece datos abiertos por API (por ejemplo, el portal de datos abiertos del Gobierno). Anota qué datos ofrece y en qué formato.

🎯 Objetivo de aprendizaje#

• Identificar el endpoint de una API.
• Hacer una petición GET con la biblioteca requests.

📖 Explicación conceptual#

Endpoint (punto final): es la dirección donde están los datos, normalmente una URL. Si quieres sacar dinero de un banco, necesitas saber dónde queda.

Petición (request): es como ir al banco y hablar con el cajero, que actúa como la API: no te deja entrar a la bóveda, pero atiende tus solicitudes. Algunas requieren identificarte (retirar dinero); otras no (preguntar el horario). Hoy usaremos APIs del segundo tipo: no piden identificación.

La API de la ubicación de la ISS:

http://api.open-notify.org/iss-now.json

Si pegas esa dirección en el navegador, verás algo así (respuesta real del 26/09/2026):

{"message": "success", "iss_position": {"latitude": "29.1542", "longitude": "40.0602"}, "timestamp": 1790444272}

Si recargas la página, los números cambian: la ISS se mueve muy rápido.

💡 El curso recomienda una extensión del navegador para ver el JSON en forma de árbol (JSON Viewer Awesome). Algunos navegadores, como Firefox, ya lo muestran así sin instalar nada.

¿Por qué JSON? La analogía del curso: un mueble de IKEA viene en un paquete plano para transportarlo fácil, y en casa lo armas. JSON es ese paquete plano: texto compacto que viaja rápido por internet y que en Python "armamos" de nuevo como diccionario.

🔎 Ejemplo explicado#

import requests

response = requests.get(url="http://api.open-notify.org/iss-now.json")
print(response)          # <Response [200]>

• requests no viene con Python: hay que instalarlo (en PyCharm, con el bombillo rojo; o con pip install requests).
• requests.get hace una petición de tipo GET (obtener datos) al endpoint.
• Al imprimir la respuesta no vemos el JSON, sino <Response [200]>: un código de estado. Lo estudiamos en la siguiente sección.

⚠️ Errores frecuentes#

Retos adicionales (creados para esta adaptación)#

• 🟢 Reto 1: abre el endpoint en el navegador 3 veces con un minuto de diferencia y anota la latitud y longitud. ¿Hacia dónde se mueve la ISS?
• 🟡 Reto 2: haz la misma petición desde Python e imprime response.text. ¿Qué tipo de dato es?
• 🟠 Reto 3: mide cuánto tarda la respuesta (investiga response.elapsed).
• 🔴 Reto 4: el endpoint http://api.open-notify.org/astros.json dice quiénes están en el espacio. Consúltalo y compara la lista con una fuente de noticias reciente. ¿Coinciden? (Ver sección 3, "Datos que no son confiables".)

🎯 Objetivo de aprendizaje#

• Interpretar los códigos de estado HTTP.
• Lanzar una excepción cuando la petición falla.
• Extraer datos del JSON de la respuesta.

📖 Los códigos de estado#

El primer dígito resume lo que pasó:

🛠️ Nota técnica: en el video, los 3xx se describen como "no tienes permiso, vete". En realidad significan redirección: el recurso se movió a otra dirección. La falta de permiso se indica con códigos 4xx, como 401 (no autenticado) o 403 (prohibido). Consulta la referencia de códigos de estado de MDN (se abre en otra pestaña).

📖 ¿Qué hacer si la petición falla?#

El curso muestra el razonamiento paso a paso:

1. Tentación: if response.status_code != 200: print("error"). Imprimir no sirve: el programa sigue como si nada.
2. Mejor: lanzar una excepción, raise Exception("Bad response from ISS API"). Pero es demasiado general.
3. Más específico: un if/elif para 404, 401, … Pero hay decenas de códigos: imposible cubrirlos todos.
4. Solución: que requests lance la excepción adecuada:

response = requests.get(url="http://api.open-notify.org/iss-now.json")
response.raise_for_status()

Si el código no es de éxito, raise_for_status() lanza una HTTPError con un mensaje claro. Con un endpoint mal escrito (verificado):

HTTPError: 404 Client Error: Not Found for url: http://api.open-notify.org/iss-now.jsonx

📖 Extraer los datos#

data = response.json()
longitude = data["iss_position"]["longitude"]
latitude = data["iss_position"]["latitude"]
iss_position = (longitude, latitude)
print(iss_position)

• response.json() convierte el JSON en un diccionario de Python.
• iss_position es un diccionario anidado: se accede con dos pares de corchetes.
• ⚠️ La latitud y la longitud llegan como texto ("29.1542"), no como números. Para compararlas hay que usar float(...) (sección 6).

Para ver en un mapa dónde está la ISS, el curso usa latlong.net (se abre en otra pestaña) (Lat Long to Address).

📖 Datos que no son confiables (análisis de esta adaptación)#

raise_for_status() solo detecta los errores que el servidor reporta con su código. Dos casos reales, verificados el 26/09/2026:

• http://api.open-notify.org/astros.json responde 200, pero la lista de astronautas corresponde a una tripulación de 2024: los datos están desactualizados.
• https://restcountries.com/v3.1/..., una API de países muy usada en tutoriales, responde 200 pero su contenido dice "success": false y que esa versión fue retirada.

Conclusión: un código 200 significa "el servidor respondió", no "los datos son correctos". Revisa también el contenido y compáralo con otras fuentes.

⚠️ Errores frecuentes#

Retos adicionales (creados para esta adaptación)#

• 🟢 Reto 1: provoca a propósito un 404 y captúralo con try/except requests.exceptions.HTTPError, mostrando un mensaje amable.
• 🟡 Reto 2: desconecta el internet y ejecuta la petición. ¿Qué excepción aparece? Captúrala también.
• 🟠 Reto 3: convierte el timestamp de la respuesta en una fecha legible (investiga datetime.fromtimestamp).
• 🔴 Reto 4: escribe obtener_posicion_iss() que devuelva una tupla de floats (lat, lng), o None si hubo cualquier error (HTTP, conexión o tiempo de espera con timeout=10).

📝 Ejercicio original del curso#

Enunciado: el curso entrega una aplicación Tkinter ya construida (con background.png y kanye.png) que muestra una cita dentro de un lienzo. Al pulsar el botón con la cara de Kanye West se llama get_quote(). Tu trabajo: completar esa función para que traiga una cita aleatoria de la API https://api.kanye.rest y la muestre en quote_text.

La API devuelve un JSON con una sola clave (verificado):

{"quote": "People always tell you 'Be humble. Be humble.' When was the last time someone told you to be amazing? ..."}

🔍 Antes de programar#

• ¿Qué clave del JSON contiene la cita?
• ¿Cómo se cambiaba el texto de un elemento del lienzo? (Día 31)

🔎 La solución del curso#

def get_quote():
    response = requests.get("https://api.kanye.rest")
    response.raise_for_status()
    data = response.json()
    quote = data["quote"]
    canvas.itemconfig(quote_text, text=quote)

🏫 Nota para el aula (adaptación): las citas llegan de una API externa y no podemos controlar su contenido. Si el docente prefiere otra fuente, la API https://api.adviceslip.com/advice (consejos cortos en inglés, sin clave) funciona igual; su JSON es anidado: data["slip"]["advice"] (verificado).

Si no tienes el archivo inicial: construye una ventana con un Canvas que tenga un texto (quote_text) y un botón que llame a get_quote. Es la estructura de Flashy (Día 31), más sencilla.

Retos adicionales (creados para esta adaptación)#

• 🟢 Reto 1: muestra la primera cita al abrir la aplicación, sin esperar al botón.
• 🟡 Reto 2: si la API falla (sin internet), muestra en el lienzo "No se pudo obtener la cita" en lugar de cerrar el programa.
• 🟠 Reto 3: agrega un botón Guardar que añada la cita actual a un archivo favoritas.txt, sin repetirlas.
• 🔴 Reto 4: las citas largas se salen del lienzo. Investiga el parámetro width de create_text y reduce el tamaño de la letra si la cita supera cierto número de caracteres.

🎯 Objetivo de aprendizaje#

• Enviar parámetros en una petición.
• Leer la documentación de una API para saber qué parámetros acepta.
• Extraer la hora de una fecha en formato ISO con split.

📖 Explicación conceptual#

Los parámetros son entradas que cambian la respuesta, igual que los argumentos de una función. En el banco: en vez de "¿cuál es su horario?", preguntas "¿a qué hora cierran el lunes?".

• Algunas APIs no tienen parámetros (la de la ISS).
• Otras tienen parámetros obligatorios y opcionales. Los opcionales tienen un valor por defecto, como los parámetros de las funciones.

La API de amanecer y atardecer: https://api.sunrise-sunset.org/json

🔎 La solución del curso, paso a paso#

1. Sin parámetros: error 400 (Bad Request): ¿cómo va a saber la hora del amanecer si no le dices dónde estás? (Verificado: {"results":"","status":"INVALID_REQUEST"}.)

2. Con los parámetros en un diccionario: las claves deben ser exactamente las de la documentación. Tu latitud y longitud se buscan en latlong.net; incluye el signo negativo si lo tiene (en Colombia, la longitud es negativa):

MY_LAT = 4.711       # ejemplo: Bogotá (busca las de tu municipio)
MY_LONG = -74.0721

parameters = {
    "lat": MY_LAT,
    "lng": MY_LONG,
    "formatted": 0,
}

response = requests.get("https://api.sunrise-sunset.org/json", params=parameters)
response.raise_for_status()
data = response.json()
sunrise = data["results"]["sunrise"]
sunset = data["results"]["sunset"]

3. Los parámetros en la URL: requests los agrega así: https://api.sunrise-sunset.org/json?lat=4.711&lng=-74.0721&formatted=0. El ? inicia los parámetros y el & los separa. Puedes pegar esa URL en el navegador para ver la respuesta.

4. Extraer la hora con split: con formatted=0, la respuesta es "2026-09-26T10:43:35+00:00" (verificado):

sunrise_hour = int(sunrise.split("T")[1].split(":")[0])

5. Comparar con la hora actual: datetime.now().hour, que ya está en formato de 24 horas.

🛠️ Nota técnica (muy importante en Colombia): las horas de esta API están en UTC (fíjate en el +00:00). El curso se grabó en Londres, donde la hora local coincide con UTC buena parte del año, así que no se nota el problema. En Colombia (UTC−5), para Bogotá el 26/09/2026 la API dice amanecer a las 10 y atardecer a las 22 (verificado), pero en la hora local son las 5:43 y las 17:51. Si comparas esas horas con datetime.now().hour, que es la hora local, el resultado es incorrecto. Solución: agrega el parámetro "tzid": "America/Bogota" y la API devuelve "2026-09-26T05:43:35-05:00" (verificado).

⚠️ Errores frecuentes#

Retos adicionales (creados para esta adaptación)#

• 🟢 Reto 1: imprime la hora del amanecer y del atardecer de tu municipio en formato 05:43.
• 🟡 Reto 2: usa el parámetro date para averiguar la hora del atardecer del día de tu cumpleaños.
• 🟠 Reto 3: usa day_length (duración del día en segundos) y muéstralo en horas y minutos.
• 🔴 Reto 4: extrae la hora y los minutos para decidir si "ya se puso el sol" con precisión de minutos, no solo de horas. (Investiga datetime.fromisoformat, que convierte el texto completo en un objeto datetime.)

Problema#

Enviarte un correo cuando la ISS esté cerca de tu posición y sea de noche.

Contexto#

La ISS solo se ve a simple vista cuando el cielo está oscuro y pasa relativamente cerca. El programa combina dos APIs (posición de la ISS y amanecer/atardecer), datetime y smtplib.

Requisitos funcionales (del curso)#

1. Si la ISS está cerca de tu posición (±5 grados de latitud y de longitud)…
2. …y es de noche…
3. …envíate un correo: "¡Mira hacia arriba! La ISS está sobre ti".
4. Desafío extra del curso: repetir la comprobación cada 60 segundos.

Pistas del curso:

• Las horas del amanecer y del atardecer son texto: conviértelas con int().
• La posición de la ISS también es texto: conviértela con float().
• Crea una función que devuelva True si la ISS está a ±5 grados.

Planificación#

🔍 Antes de programar#

• Entradas: tu latitud y longitud, la posición de la ISS, la hora del amanecer, del atardecer y la actual.
• Proceso: dos preguntas de sí o no. ¿Cuáles? ¿Qué función responde cada una?
• Salida: un correo.
• Si tu latitud es 4,7, ¿entre qué valores debe estar la latitud de la ISS para que cuente como "cerca"?

Construcción paso a paso (solución del curso)#

Versión 1 — ¿Está cerca la ISS?

def is_iss_overhead():
    response = requests.get(url="http://api.open-notify.org/iss-now.json")
    response.raise_for_status()
    data = response.json()
    iss_latitude = float(data["iss_position"]["latitude"])
    iss_longitude = float(data["iss_position"]["longitude"])

    if MY_LAT - 5 <= iss_latitude <= MY_LAT + 5 and MY_LONG - 5 <= iss_longitude <= MY_LONG + 5:
        return True

La expresión a <= x <= b comprueba que x esté entre a y b.

Versión 2 — ¿Es de noche?

def is_night():
    parameters = {"lat": MY_LAT, "lng": MY_LONG, "formatted": 0}
    response = requests.get("https://api.sunrise-sunset.org/json", params=parameters)
    response.raise_for_status()
    data = response.json()
    sunrise = int(data["results"]["sunrise"].split("T")[1].split(":")[0])
    sunset = int(data["results"]["sunset"].split("T")[1].split(":")[0])

    time_now = datetime.now().hour
    if time_now >= sunset or time_now <= sunrise:
        return True

El curso encontró un error: primero comparaba datetime.now() (un objeto datetime) con números enteros. La corrección fue usar datetime.now().hour.

Versión 3 — El correo. Si is_iss_overhead() and is_night(), se envía el correo como en el Día 32.

Versión final — Repetir cada 60 segundos:

while True:
    time.sleep(60)
    if is_iss_overhead() and is_night():
        # enviar el correo

El programa ya no termina: sigue funcionando mientras el computador esté encendido.

Pruebas#

Es difícil esperar a que la ISS pase de noche. Para probar, simula las condiciones:

🧪 Prueba y depuración#

1. La hora UTC (análisis de esta adaptación). Con las horas UTC de Bogotá (amanecer 10, atardecer 22) y la hora local, así responde el is_night() del curso:

(Simulación verificada.) Corrige la función con tzid y repite la tabla.

2. Correos repetidos. Con el bucle cada 60 s, mientras la ISS esté cerca llega un correo por minuto. ¿Cómo haces que llegue uno solo por paso de la ISS?
3. Peticiones innecesarias. El bucle consulta la hora del amanecer cada minuto, aunque solo cambia una vez al día. Guárdala y consúltala una sola vez por día.
4. Sin internet o API caída. Una sola falla lanza una excepción y detiene el bucle para siempre. Captura requests.exceptions.RequestException y agrega timeout=10 a cada petición para que el programa no se quede esperando indefinidamente.
5. La línea de cambio de fecha. Si tu longitud fuera 178, la ISS en −179 está a solo 3 grados, pero la resta da 357. No afecta a Colombia, pero ¿cómo lo corregirías?

⭐ Extensión del proyecto#

• Mostrar en el correo la posición exacta y un enlace a un mapa.
• Registrar en un CSV cada vez que la ISS pasa cerca (fecha, hora, posición).
• Usar el "crepúsculo civil" (civil_twilight_end) en lugar del atardecer: el cielo está más oscuro.

Situación#

En clase de Ciencias Naturales se preguntan: ¿por qué en Colombia los días duran casi lo mismo todo el año, mientras que en otros países cambian mucho? Vamos a comprobarlo con datos reales.

Requisitos#

1. Un diccionario con al menos 6 ciudades: 4 de Colombia de distintas regiones (por ejemplo, Leticia, Riohacha, San Andrés y tu municipio) y 2 lejos del ecuador (por ejemplo, Ushuaia y Oslo). Busca tú sus coordenadas en latlong.net.
2. Para cada ciudad, consultar la API de amanecer y atardecer con formatted=0 y su tzid (investiga la zona horaria de cada ciudad).
3. Mostrar una tabla con: ciudad, amanecer, atardecer y duración del día en horas y minutos (day_length).
4. Repetir la consulta para cuatro fechas del año (21 de marzo, 21 de junio, 23 de septiembre y 21 de diciembre) usando el parámetro date.
5. Guardar los resultados en reloj_solar.csv con pandas.
6. Responder con los datos: ¿cuántos minutos varía la duración del día en Bogotá entre junio y diciembre? ¿Y en Oslo?
7. Manejar errores de red sin detener el programa: si una ciudad falla, se informa y se sigue con las demás.

Decisiones que debes tomar#

• ¿Cómo organizas el código para no repetir la petición 24 veces (6 ciudades × 4 fechas)?
• ¿Muestras los resultados en la consola, en Tkinter o en ambos?

Casos de prueba#

Situación problema#

El club de astronomía del colegio quiere observar la ISS. Necesita un sistema que avise a los miembros del club cuando la ISS pase cerca de noche, sin llenarlos de correos, y que lleve un registro de los pasos para planear observaciones.

Pregunta orientadora#

¿Cómo construir un programa que tome decisiones con datos en vivo de varias APIs y que siga funcionando aunque internet o una API fallen?

Objetivo#

Construir un servicio de consola que revise cada minuto la posición de la ISS y envíe una alerta por paso a los miembros del club.

Requerimientos#

1. miembros.csv con nombres y correos ficticios, y un campo activo (sí/no).
2. config.json con la ubicación del colegio, el margen en grados, el intervalo de revisión y el servidor de correo.
3. Hora del amanecer y del atardecer con tzid correcto, consultada una vez al día.
4. Detección de "paso": desde que la ISS entra en el margen hasta que sale. Un solo correo por paso.
5. Correo con EmailMessage (tildes y ñ correctas) a todos los miembros activos.
6. pasos.csv con cada paso detectado: fecha, hora de inicio, hora de fin y si fue de noche.
7. Manejo de HTTPError, ConnectionError y Timeout: el programa espera y vuelve a intentar, sin detenerse.
8. Un modo simulación (en config.json) que use posiciones falsas de la ISS para poder probar en clase.

Restricciones#

• Todas las peticiones con timeout.
• Ninguna contraseña en el código (variables de entorno, Día 32).
• Funciones separadas para: obtener posición, decidir si está cerca, decidir si es de noche, enviar correo y registrar.

Etapas de desarrollo#

Entregables#

• Código organizado en funciones, config.json y datos ficticios.
• Tabla de 10 casos de prueba con resultados.
• Registro de errores con al menos 5 errores reales.
• pasos.csv de al menos 24 horas de ejecución real (si es posible) o de la simulación.

Casos de prueba mínimos#

Criterios técnicos de funcionamiento#

• El programa corre al menos 1 hora sin detenerse.
• La API de amanecer y atardecer se consulta una vez al día, no cada minuto.
• Cambiar la ubicación o el margen solo requiere editar config.json.

Posibles extensiones#

Interfaz Tkinter con un mapa sencillo y la posición de la ISS actualizada con after; estadística semanal de pasos nocturnos.

Conceptuales#

1. Explica con tus palabras qué es un endpoint y qué es un parámetro.
2. ¿Qué significa un código 404? ¿Y un 500? ¿De quién es la culpa en cada caso?
3. ¿Por qué raise_for_status() es mejor que escribir un if para cada código?
4. ¿Por qué un código 200 no garantiza que los datos sean correctos?

Análisis de código#

parameters = {"lat": MY_LAT, "lng": MY_LONG, "formatted": 0}
response = requests.get("https://api.sunrise-sunset.org/json", params=parameters)

¿Qué URL completa se envía? ¿Qué pasaría si quitaras "lng"?

Predicción#

1. ¿Qué devuelve "2026-09-26T17:51:28-05:00".split("T")[1].split(":")[0]? ¿De qué tipo es?
2. Con MY_LAT = 4.7, ¿la ISS en latitud "9.2" está "cerca" según la función del curso? ¿Y en "10.1"?

Depuración#

data = response.json()
iss_latitude = data["iss_position"]["latitude"]
if MY_LAT - 5 <= iss_latitude <= MY_LAT + 5:
    print("¡Cerca!")

Este código produce un error. ¿Cuál y por qué?

def is_iss_overhead():
    ...
    if cerca:
        return True

Un compañero dice que la función "devuelve False si no está cerca". ¿Es cierto? ¿Qué devuelve realmente? ¿Importa en un if?

Modificación#

Cambia el margen de ±5 grados por una constante y haz que el correo diga a cuántos grados de distancia está la ISS.

Creación#

Escribe es_de_noche(hora_actual, hora_amanecer, hora_atardecer) que no haga ninguna petición (solo reciba números) y pruébala con 6 horas distintas. ¿Por qué es más fácil de probar que la versión del curso?