# Guide de démarrage rapide

## 1. Configuration initiale

### Installer le package
```bash
# Installation depuis le repository local
pip install -e .

# Ou installation des dépendances seulement
pip install requests>=2.25.0
```

### Configurer vos credentials
```bash
# Option 1: Script automatique
python examples/setup_credentials.py

# Option 2: Manuelle
cp credentials.json.example credentials.json
# Puis éditer credentials.json avec vos identifiants
```

## 2. Test de connexion

```bash
python tests/test_real_connection.py
```

## 3. Premier script

```python
from atmo_data_wrapper import AtmoDataClient

# Connexion automatique
client = AtmoDataClient()
client.auto_login()

# Récupérer les indices ATMO d'Île-de-France
indices = client.get_indices_atmo(aasqa="11")

# Afficher les résultats
print(f"Récupéré {len(indices)} indices")
for indice in indices:
    print(f"{indice.lib_zone}: {indice.get_qualificatif()}")

# Afficher la source des données (obligatoire)
from atmo_data_wrapper import get_atmo_licence
print(f"\nSource: {get_atmo_licence('courte')}")
```

## 4. Exemples disponibles

### Scripts d'introduction
- `examples/example_usage.py` - Tous les endpoints avec données brutes
- `examples/example_data_models.py` - Objets typés et méthodes helper
- `examples/example_save_files.py` - Sauvegarde en différents formats
- `examples/example_aasqa_utilities.py` - Fonctions utilitaires AASQA
- `examples/demo_licence_atmo.py` - Mentions légales et licence

### Scripts de démonstration complète
- `demos/demo_atmo_functions.py` - **Toutes les fonctionnalités IndiceAtmo**
- `demos/demo_pollen_functions.py` - **Toutes les fonctionnalités IndicePollen**
- `demos/demo_emission_functions.py` - **Toutes les fonctionnalités EmissionData**
- `demos/demo_episode_functions.py` - **Toutes les fonctionnalités EpisodePollution**

**Recommandé** : Commencer par les scripts de démonstration pour voir toutes les possibilités !

## 5. Structure des données

### Objets typés disponibles
- **IndiceAtmo** : Qualité de l'air avec helpers (couleurs, qualificatifs, émojis)
- **EpisodePollution** : Épisodes avec niveaux d'alerte et géométries
- **EmissionData** : Émissions avec calculs par habitant/km² et secteurs
- **IndicePollen** : Pollens avec détection des risques et taxons responsables

### Méthodes utiles
```python
# Qualité de l'air
indice.get_qualificatif()     # "Bon", "Moyen", etc.
indice.get_color()            # Couleur hex et RGB
indice.get_emoji("round")     # Émojis ronds 🟢
indice.get_emoji("square")    # Émojis carrés 🟩
indice.is_poor_quality()      # Bool

# Pollens
pollen.get_responsible_pollens()  # ["Armoise", "Graminées"]
pollen.get_pollens_summary()      # Détail avec émojis

# Émissions et épisodes
emission.get_emission_per_capita('nox')  # kg/hab/an
episode.get_alert_level()                # "Information"/"Alerte"

# Collections
indices.get_statistics()            # Stats globales
indices.filter_by_aasqa("11")      # Filtrage par région
indices.filter_by_coordinates(...)  # Filtrage géographique
```

## 6. Formats de sortie

- **GeoJSON** (défaut) → Objets typés avec méthodes helper
- **CSV** → Dictionnaires Python bruts

## 7. Sauvegarde

```python
# Sauvegarder les résultats
client.save_to_file(indices, "data/indices", "json")
client.save_to_file(indices, "data/indices", "csv") 
client.save_to_file(indices, "data/indices", "geojson")
```

## 8. Codes utiles

### Régions (AASQA)
```python
from atmo_data_wrapper import get_aasqa_by_department, get_aasqa_info

# Trouver l'AASQA d'un département
aasqa = get_aasqa_by_department("54")  # Nancy -> "44" (Grand Est)

# Infos complètes
info = get_aasqa_info("44")
print(info['organisme'])    # "ATMO Grand-Est"
print(info['site_web'])     # URL officielle
```

Codes principaux :
- `11` : Île-de-France (Airparif)
- `44` : Grand Est (ATMO Grand-Est) 
- `93` : PACA (AtmoSud)
- `84` : Auvergne-Rhône-Alpes

### Polluants
- `NO2`, `SO2`, `O3`, `PM10`, `PM2.5`

## 9. Dépannage

```bash
# Vérifier la configuration
python tests/test_credentials_system.py

# Test complet
python tests/test_real_connection.py

# Debug d'un endpoint spécifique
python -c "
from atmo_data_wrapper import AtmoDataClient
client = AtmoDataClient()
client.auto_login()
print(client.get_indices_atmo())
"

# Exécution des tests
python -m pytest tests/
```