aemet-api/README.md

Cliente TypeScript para la API de AEMET (Agencia Estatal de Meteorología)

��# AEMET API Unofficial

Este proyecto proporciona un cliente TypeScript/JavaScript para interactuar con la API de AEMET (Agencia Estatal de Meteorolog�a) en Espa�a. Permite obtener datos meteorol�gicos, predicciones y valores climatol�gicos de manera sencilla y eficiente. Este cliente est� disponible como un paquete npm llamado `aemet-api`.

## Tabla de Contenidos

- [Instalaci�n](#instalaci�n)
- [Uso](#uso)
- [Estructura del Proyecto](#estructura-del-proyecto)
- [Ejemplos](#ejemplos)
- [M�todos de la Clase Aemet](#m�todos-de-la-clase-aemet)
- [Pruebas](#pruebas)
- [Contribuciones](#contribuciones)
- [Licencia](#licencia)

## Instalaci�n

Para instalar el paquete, puedes usar npm:

```bash
npm install aemet-api
```

O si prefieres clonar el repositorio y trabajar directamente con el c�digo fuente:

1. Clona el repositorio:
   ```bash
   git clone https://github.com/tu_usuario/tu_repositorio.git
   cd tu_repositorio
   ```

2. Instala las dependencias:
   ```bash
   npm install
   ```

3. Crea un archivo `.env` en la ra�z del proyecto y a�ade tu clave de API de AEMET:
   ```plaintext
   AEMET_API_KEY=tu_api_key
   ```

## Uso

Para utilizar el cliente de AEMET, primero debes importar la clase `Aemet` y crear una instancia con tu clave de API. Aqu� hay un ejemplo b�sico:

```typescript
import { Aemet } from 'aemet-api'; // Cambia la ruta si usas el c�digo fuente
import dotenv from 'dotenv';

dotenv.config();

const apiKey = process.env.AEMET_API_KEY;
const aemet = new Aemet(apiKey);

// Ejemplo de uso
async function obtenerPrediccion() {
    const codigoMunicipio = '28079'; // C�digo del municipio de Madrid
    const prediccion = await aemet.getSimpleForecast(codigoMunicipio);
    console.log(prediccion);
}

obtenerPrediccion();
```

## Estructura del Proyecto

El proyecto est� organizado en varias carpetas y archivos:

- **src/**: Contiene el c�digo fuente del cliente AEMET.
  - **aemet.ts**: Clase principal que maneja la interacci�n con la API de AEMET.
  - **lib/**: Contiene utilidades, constantes y tipos utilizados en el cliente.
  - **tests/**: Contiene pruebas unitarias para asegurar la funcionalidad del cliente.
  - **examples/**: Ejemplos de uso del cliente para diferentes funcionalidades.
  - **index.ts**: Punto de entrada principal para la librer�a.

## Ejemplos

El directorio `examples` contiene varios scripts que demuestran c�mo utilizar la API de AEMET:

### 1. Obtener Predicci�n Simplificada

```typescript
import { Aemet } from 'aemet-api';
import dotenv from 'dotenv';

dotenv.config();

const aemet = new Aemet(process.env.AEMET_API_KEY);

async function obtenerPrediccionSimplificada() {
    const codigoMunicipio = '28079'; // Madrid
    try {
        const prediccion = await aemet.getSimpleForecast(codigoMunicipio);
        console.log('Predicci�n Simplificada:', prediccion);
    } catch (error) {
        console.error('Error al obtener la predicci�n:', error);
    }
}

obtenerPrediccionSimplificada();
```

### 2. Obtener Predicci�n Completa

```typescript
async function obtenerPrediccionCompleta() {
    const codigoMunicipio = '28079'; // Madrid
    try {
        const prediccionCompleta = await aemet.getForecast(codigoMunicipio);
        console.log('Predicci�n Completa:', JSON.stringify(prediccionCompleta, null, 2));
    } catch (error) {
        console.error('Error al obtener la predicci�n completa:', error);
    }
}

obtenerPrediccionCompleta();
```

### 3. Listar Municipios Disponibles

```typescript
async function listarMunicipios() {
    try {
        const municipios = await aemet.getMunicipalities();
        console.log('Municipios Disponibles:', municipios);
    } catch (error) {
        console.error('Error al listar municipios:', error);
    }
}

listarMunicipios();
```

### 4. Obtener Alertas Meteorol�gicas

```typescript
async function obtenerAlertasHoy() {
    try {
        const alertas = await aemet.getAlertsToday();
        console.log('Alertas Meteorol�gicas de Hoy:', alertas);
    } catch (error) {
        console.error('Error al obtener alertas:', error);
    }
}

obtenerAlertasHoy();
```

## M�todos de la Clase Aemet

La clase `Aemet` incluye varios m�todos �tiles para interactuar con la API de AEMET:

- **getSimpleForecast(municipalityCode: string)**: Obtiene la predicci�n simplificada para un municipio dado su c�digo INE (5 d�gitos). Devuelve un objeto con la predicci�n para hoy, ma�ana y pasado ma�ana.

- **getForecast(municipalityCode: string)**: Obtiene la predicci�n completa para un municipio, incluyendo datos crudos.

- **getMunicipalities()**: Devuelve una lista de municipios disponibles con sus c�digos.

- **getProvinces()**: Devuelve una lista de provincias disponibles.

- **getAlertsToday()**: Obtiene los avisos meteorol�gicos para el d�a actual.

- **getAlertsTomorrow()**: Obtiene los avisos meteorol�gicos para el d�a siguiente.

- **getWeatherStations()**: Devuelve una lista de estaciones meteorol�gicas disponibles.

- **searchWeatherStations(query: string)**: Busca estaciones por nombre o provincia.

- **getClimateValues(params: ClimateValuesParams)**: Obtiene valores climatol�gicos diarios para una estaci�n y per�odo espec�ficos.

- **getClimateSummaryByProvincia(params: ClimateValuesParams, provincia: string)**: Obtiene un resumen climatol�gico para una estaci�n y per�odo, filtrando por provincia.

## Pruebas

Para ejecutar las pruebas, utiliza los siguientes comandos:

```bash
# Ejecutar todos los tests
npm test

# Ejecutar tests en modo watch
npm run test:watch

# Ejecutar tests con informe de cobertura
npm run test:coverage
```

Las pruebas est�n organizadas en el directorio `tests` y utilizan Jest para la ejecuci�n de pruebas.

## Contribuciones

Las contribuciones son bienvenidas. Si deseas contribuir, por favor sigue estos pasos:

1. Haz un fork del repositorio.
2. Crea una nueva rama (`git checkout -b feature/nueva-caracteristica`).
3. Realiza tus cambios y haz commit (`git commit -m 'A�adir nueva caracter�stica'`).
4. Haz push a la rama (`git push origin feature/nueva-caracteristica`).
5. Abre un Pull Request.

## Licencia

Este proyecto est� bajo la Licencia MIT. Consulta el archivo [LICENSE](LICENSE) para m�s detalles.

## Nuevas funcionalidades

### Predicci�n horaria por municipio

Se ha a�adido soporte para el endpoint de predicci�n horaria por municipio:

```
GET /api/prediccion/especifica/municipio/horaria/{municipio}
```

Este endpoint proporciona predicci�n horaria para el municipio especificado, presentando informaci�n de hora en hora hasta 48 horas.

### C�mo usar la predicci�n horaria

#### M�todo 1: Usando getClimateValues con c�digo de municipio

```typescript
import { Aemet } from './src/aemet';

// Inicializar cliente
const aemet = new Aemet('TU_API_KEY');

// Configurar par�metros
const params = {
  startDate: '2023-09-01',
  endDate: '2023-09-01',
  municipalityCode: '28079' // Madrid
};

// Obtener predicci�n horaria
const resultado = await aemet.getClimateValues(params);
console.log(resultado);
```

#### M�todo 2: Usando getWeatherByCoordinates con c�digo de municipio

```typescript
import { Aemet } from './src/aemet';

// Inicializar cliente
const aemet = new Aemet('TU_API_KEY');

// Obtener predicci�n horaria
const resultado = await aemet.getWeatherByCoordinates(
  40.4165, // latitud (se ignora si se proporciona municipalityCode)
  -3.7026, // longitud (se ignora si se proporciona municipalityCode)
  '28079'  // Madrid
);
console.log(resultado);
```

### Ejemplos

Se ha incluido un ejemplo completo en el directorio `src/examples/`:

```
src/examples/prediccion_horaria.ts
```

Para ejecutar el ejemplo:

```bash
# Instalar dependencias
npm install

# Ejecutar ejemplo (recuerda reemplazar TU_API_KEY en el c�digo)
npx ts-node src/examples/prediccion_horaria.ts
```

### Exploraci�n de la estructura de datos

Como la estructura exacta de la respuesta de este endpoint no est� completamente documentada, se incluye el campo `rawData` en la respuesta para facilitar la exploraci�n de los datos devueltos por la API.

```typescript
// Acceder a los datos crudos
console.log(JSON.stringify(resultado.rawData, null, 2));
```

### Notas

- Esta funcionalidad est� en fase experimental y la estructura de datos podr�a cambiar.
- Se requiere una clave API v�lida de AEMET para usar este cliente.