py_atmo_data_wrapper/docs/QUICKSTART.md

Guide de démarrage rapide

1. Configuration initiale

Installer le package

# Installation depuis le repository local
pip install -e .

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

Configurer vos credentials

# 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

python tests/test_real_connection.py

3. Premier script

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

# 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

# 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)

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

# 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/