Merge pull request #31 from FEFO2/new-feature

world bank proyect designed

Author: alesanchezr

INSTRUCTIONS.es.md

@@ -1,143 +1,129 @@
-# Interactuando con la API de Spotify
+# Interactuando con la API v2 del World Bank
 
-Spotify se puede utilizar como fuente de datos para varios proyectos de ciencia de datos. En este ejercicio, aprenderemos a interactuar con la API de esta red social. `Spotipy` es una librería de código abierto y para Python que permite hacer un uso a alto nivel de la API de Spotify.
+En este proyecto vas a construir un flujo de datos completo: consumo de API, transformacion a DataFrame, analisis visual y carga a base de datos SQL.
 
-## Paso 1: Crear una cuenta de desarrollador de Spotify
+## Contexto del ejercicio
 
-Antes de comenzar a programar, necesitas acceso a las credenciales de desarrollador de Spotify. Visita [developer.spotify.com](https://developer.spotify.com/documentation/web-api).
+Trabajaras con la API publica del World Bank v2 (sin autenticacion). El objetivo es analizar la evolucion socioeconomica y ambiental de 5 paises elegidos por ti entre 2010 y 2024.
 
-- Inicia sesión con tu cuenta de Spotify (o crea una si aún no tienes una).
+### Seleccion del dataset
 
-- Ve a Dashboard y haz clic en Create an App. Completa los campos requeridos. En Redirect URI, escribe: `http://localhost/`
+1. Elige 5 paises (ISO3) que te interesen.
+2. Elige los indicadores que quieras analizar.
+3. Recomendacion de indicadores (opcional):
 
+- `SP.POP.TOTL`: Poblacion total
+- `NY.GDP.PCAP.CD`: PIB per capita (USD actuales)
+- `EN.ATM.CO2E.PC`: Emisiones de CO2 per capita (toneladas metricas)
+- `SP.DYN.LE00.IN`: Esperanza de vida al nacer (anios)
 
-![Spotify create app](https://github.com/4GeeksAcademy/interacting-with-api-python-project-tutorial/blob/main/assets/spotify_1.PNG?raw=true)
+API base: `https://api.worldbank.org/v2`
 
+## Requisitos tecnicos
 
-Una vez creada la app, dirígete a la sección **Settings** para copiar tu `Client ID` y `Client Secret`. Los usarás más adelante para autenticarte ante la API.
+Debes trabajar en un archivo `.ipynb` y usar:
 
-## Paso 2: Configuración inicial
+- `requests`
+- `pandas`
+- `matplotlib` y/o `seaborn`
+- `sqlalchemy`
 
-- Abre la terminal y asegúrate de tener instalada la librería `Spotipy`, que es la que usaremos para conectarnos con la API de Spotify:
+## Paso 1: Preparar entorno
 
-    ```bash
-    pip install spotipy
-    ```
+Instala dependencias:
 
-## Paso 3: Variables de entorno
-
-Ya tienes el archivo `.env` en la raíz del proyecto. Asegúrate de que contenga las siguientes variables con tus credenciales de Spotify (reemplaza el contenido con tus propios datos):
-
-```env
-CLIENT_ID=your_client_id
-CLIENT_SECRET=your_client_secret
+```bash
+pip install requests pandas matplotlib seaborn sqlalchemy
 ```
 
-> ⚠️ Es importante que coloques tus datos en las variables de entorno para evitar exponer tus credenciales si subes el proyecto a un repositorio.
-
-Ahora, en el archivo `app.py`, agrega el siguiente código para leer las variables de entorno:
-
-```python
-import os
-import pandas as pd
-import seaborn as sns
-from dotenv import load_dotenv
-
-# load the .env file variables
-load_dotenv()
+Crea un notebook, por ejemplo: `src/world_bank_analysis.ipynb`.
 
-# Get credential values
-client_id = os.environ.get("CLIENT_ID")
-client_secret = os.environ.get("CLIENT_SECRET")
-```
+## Paso 2: Explorar la API
 
-Con esto, tus credenciales estarán listas para ser utilizadas en la autenticación con la API de Spotify.
+Revisa estos endpoints de referencia:
 
+- Paises: `https://api.worldbank.org/v2/country`
+- Indicadores: `https://api.worldbank.org/v2/indicator`
 
-## Paso 4: Inicializar la biblioteca Spotipy
+Verifica la estructura de respuesta. La API pagina resultados (habitualmente hasta `per_page=50`), asi que debes pensar una estrategia para recorrer paginas y almacenar toda la informacion necesaria.
 
-- Importar Spotipy.
-- Realizar la conexión con la API. Para ello, puedes utilizar la función `spotipy.Spotify()`.
+Request de ejemplo en Python (plantilla):
 
 ```python
-import spotipy
-from spotipy.oauth2 import SpotifyClientCredentials
-
-auth_manager = SpotifyClientCredentials(client_id=client_id, client_secret=client_secret)
-spotify = spotipy.Spotify(auth_manager=auth_manager)
+import requests
+
+url = "https://api.worldbank.org/v2/country"
+params = {
+    "format": "json",
+    "per_page": 50,
+    "page": 1
+}
+
+response = requests.get(url, params=params, timeout=30)
+response.raise_for_status()
+payload = response.json()
+
+# payload[0] -> metadatos de paginacion
+# payload[1] -> datos de la pagina actual
+print("Metadatos:", payload[0])
+print("Primer elemento:", payload[1][0])
 ```
 
-> 💡 NOTA: Utiliza la siguiente documentación como guía sobre los parámetros: https://spotipy.readthedocs.io/en/2.22.1
-
-## Paso 5: Realizar solicitudes a la API
-
-- Comienza a interactuar con la API de Spotify: Obtén de tu artista favorito, el top 10 de sus canciones. Para ello, tendrás que buscar el `ID` del artista para usarlo en la librería. Este identificador es la dirección web que tiene el artista en Spotify:
-
-![Buscar el identificador del artista en Spotify](https://github.com/4GeeksAcademy/interacting-with-api-python-project-tutorial/blob/main/assets/spotify_2.png?raw=true)
-
-- Una vez tengas la respuesta de la API, quédate con el elemento `tracks`, que contendrá las canciones con más reproducciones del artista, quédate con el nombre de la canción, la popularidad y la duración (en minutos).
-
-> ⚠️ **NOTA** sobre posibles mensajes al ejecutar el código. Es posible que al finalizar la ejecución del script aparezca un mensaje como:
-
-```
- Exception ignored in: <function Spotify.__del__ ...>
- TypeError: isinstance() arg 2 must be a type, a tuple of types, or a union
-```
-
-Este mensaje proviene de la librería `spotipy` y **no afecta la funcionalidad de tu código ni los resultados de la API**. Puedes ignorarlo de forma segura; se trata de un detalle interno de limpieza de objetos (**garbage collection**) que no interrumpe tu análisis.
-
-
-## Paso 6: Transformar a Pandas DataFrame
 
-Puesto que el resultado obtenido en estos pasos es susceptible de tener formato de tabla, conviértelo en un DataFrame importando los datos en su formato de diccionario. A continuación, ordena las canciones por popularidad creciente y muestra el top 3 resultante.
+*IMPORTANTE:* El código mencionado arriba es orientativo. En el link de abajo tienes toda la información necesaria para llevar a cabo un llamado a la API:
 
-## Paso 7: Analizar relación estadística
+https://datahelpdesk.worldbank.org/knowledgebase/articles/898581
 
-¿Tiene relación la duración con la popularidad? ¿Podríamos decir que una canción que dure poco tiempo puede ser más popular que otra que dure más? Analízalo graficando un `scatter plot` y argumenta tu respuesta.
+## Paso 3: Descargar datos
 
+Descarga series temporales 2010-2024 para los paises e indicadores que elegiste.
 
-## ¿Te sientes con ganas de profundizar? 😎  
-**Exploración avanzada de atributos musicales - Análisis extendido con enfoque interpretativo**
+Objetivo:
 
-Si ya lograste conectarte a la API de Spotify, extraer información de tu artista favorito y representar datos básicos como popularidad y duración, te invitamos a realizar esta versión extendida del proyecto. Esta actividad opcional te permitirá incorporar nuevas variables musicales, aplicar pensamiento analítico y redactar conclusiones claras y bien fundamentadas a partir de los datos.
+- Consumir la API para varios paises e indicadores
+- Manejar paginacion cuando aplique
+- Guardar respuestas en una estructura temporal (lista de diccionarios)
 
----
+## Paso 4: Transformar respuesta a DataFrames
 
-### Propuesta 🚀  
-Aprovecha que ya tienes acceso a los datos del artista para profundizar en el análisis incluyendo nuevas métricas que ofrece la API. El objetivo es detectar patrones o características interesantes y expresarlas en un lenguaje comprensible para cualquier lector.
+Crea una tabla (DataFrame) por indicador para facilitar comparaciones entre paises.
 
-#### Variables recomendadas para explorar:
+Columnas sugeridas por tabla:
 
-- **Danceability**: Qué tan fácil es bailar la canción.
-- **Valence**: Qué tan positiva o feliz suena.
-- **Energy**: Intensidad o fuerza general.
-- **Tempo**: Velocidad (en BPM).
+- `country` 
+- `year`
+- `value`
 
----
+Limpieza minima:
 
-1. **Recupera los atributos adicionales:** Utiliza el método `audio_features()` para obtener los atributos musicales de las canciones de tu artista:
+- Eliminar filas con `value` nulo cuando sea necesario
+- Convertir `year` a entero
+- Convertir `value` a numerico
 
-    ```python
-    track_ids = [track["id"] for track in results["tracks"]]
-    features = sp.audio_features(track_ids)
-    ```
+## Paso 5: Analisis y visualizaciones
 
-2. **Crea un nuevo DataFrame con la información completa:** Combina los datos obtenidos anteriormente (`nombre, popularidad, duración`) con las nuevas métricas.
+Genera al menos 2 graficos y explica hallazgos en celdas Markdown.
 
-3. **Realiza un análisis sencillo:** Explora los valores promedio, busca extremos, identifica correlaciones visuales o estadísticamente.
+Ejemplos:
 
-    - ¿Qué valores destacan en este artista?
+1. Line chart: evolucion de un indicador por pais (2010-2024)
+2. Scatter plot: relacion entre dos indicadores para un anio reciente
 
-    - ¿Existe alguna tendencia entre popularidad y otro atributo?
+## Paso 6: Cargar resultados a base de datos SQL
 
-    - ¿Hay algo que no esperabas encontrar?
+Usa SQLite con SQLAlchemy para persistir datos:
 
-    Crea una gráfica sencilla que complemente tu conclusión.
+- Base de datos: `world_bank_analysis.db`
+- Recomendacion didactica: una tabla por indicador (ejemplo: `indicator_gdp_per_capita`, `indicator_life_expectancy`, etc.)
 
-4. **Haz visible tu trabajo:** Con base en el análisis, redacta una o dos frases que sinteticen lo que descubriste y publicalo en LinkedIn. El objetivo es comunicar tu hallazgo de forma objetiva, breve y con respaldo en los datos.
+Flujo recomendado:
 
-    > **Ejemplo:**
-    >
-    > "Las canciones más populares del artista analizado tienen un nivel de “danceability” promedio de > 0.82, lo que sugiere una clara orientación hacia lo bailable. 🕺💃 #SpotifySecrets"
+1. Crear engine con SQLAlchemy
+2. Guardar cada DataFrame con `to_sql(..., if_exists="replace")`
+3. Leer una muestra con `pd.read_sql()` para validar carga
 
+## Cierre
 
+¡Ya tienes todo para comenzar!
+Tomate tu tiempo para investigar la documentacion de la API y entender bien la estructura de las respuestas.
+Si te surge cualquier duda durante el proceso, contacta a tus mentores.