TP – API IP : Géolocalisation et classification d’adresses IP
=============================================================

Durée : 5 heures
Niveau : BTS SIO 1re année (SISR/SLAM, initiation API REST + JSON)

----------------------------------------------------------------------------------
1) Objectif pédagogique
----------------------------------------------------------------------------------
Écrire un script Python qui :
1) lit une liste d’adresses IP depuis un fichier texte,
2) interroge une API publique de géolocalisation IP (ex : ipinfo.io, ipapi.co, ipwhois.app),
3) récupère pour chaque IP : pays, fournisseur (ISP/organisation), type (datacenter/résidentiel),
4) classe les résultats par pays et par fournisseur,
5) exporte un fichier CSV et affiche un résumé en console.

----------------------------------------------------------------------------------
2) Exigences techniques
----------------------------------------------------------------------------------
- Utiliser **python-venv** pour créer un environnement isolé.
- Bibliothèques Python obligatoires :
  • requests (appel API HTTP)
  • python-dotenv (gestion clé API et configuration)
- Stocker la clé API (si nécessaire) dans un fichier `.env`.
- Ne pas commiter de secrets ni de tokens.

----------------------------------------------------------------------------------
3) Pré-requis côté plateforme
----------------------------------------------------------------------------------
- Debian 13 avec python3, venv et pip installés.
- Compte gratuit sur une API IP publique :
  Exemple : https://ipinfo.io (50 requêtes gratuites/jour).
- Exemple de fichier `ips.txt` à créer avec une centaine d'IP :

(mélange d’IP Google, Cloudflare, Fastly, Wikipédia…)
8.8.8.8
1.1.1.1
151.101.1.69
91.198.174.192
etc.

----------------------------------------------------------------------------------
4) Mise en place de l’environnement
----------------------------------------------------------------------------------
1) Créer le dossier de travail et activer le venv :
 $ mkdir tp-ip-api && cd tp-ip-api
 $ python3 -m venv .venv
 $ source .venv/bin/activate

2) Installer les bibliothèques :
 (.venv) $ python -m pip install --upgrade pip
 (.venv) $ pip install requests python-dotenv

3) Créer le fichier `.env` :
 API_URL=https://ipinfo.io
 API_TOKEN=xxxxxxxxxxxxxx

----------------------------------------------------------------------------------
5) Spécification fonctionnelle (sans code)
----------------------------------------------------------------------------------
Nom suggéré : ip_classifier.py

Entrées :
- Fichier texte `ips.txt` (une IP par ligne).
- Clé API dans `.env`.

Sorties attendues :
- Résumé en console :
• Nombre d’IP traitées
• Répartition par pays
• Répartition par fournisseur (organisation/ISP)
- Fichier CSV `ip_report.csv` avec colonnes :
• ip
• pays
• region (optionnel)
• ville (optionnel)
• organisation / ISP
• type (datacenter, résidentiel, etc. si fourni par API)

Fonctionnement :
1) Charger les IP depuis le fichier texte.
2) Pour chaque IP :
 • Appel API → récupération JSON
 • Extraction des champs utiles
 • Stockage en mémoire
3) Une fois toutes les IP traitées :
 • Générer un CSV complet
 • Calculer les statistiques (par pays, par fournisseur)
 • Afficher le résumé en console
4) Gérer les erreurs :
 • IP invalide
 • Erreur réseau / quota atteint
 • API non accessible

----------------------------------------------------------------------------------
6) Scénarios de test
----------------------------------------------------------------------------------
- Test 1 : Fichier de 4–5 IP bien connues (Google, Cloudflare, Wikipédia).
- Test 2 : Ajouter une IP privée (192.168.1.1) → vérifier la gestion d’erreur.
- Test 3 : Relancer avec une dizaine d’IP → vérifier les agrégats par pays.
- Test 4 : Vérifier la cohérence du CSV (colonnes bien formées, UTF-8).

----------------------------------------------------------------------------------
7) Livrables attendus
----------------------------------------------------------------------------------
1) Script Python (`ip_classifier.py`).
2) Fichier CSV généré (`ip_report.csv`).
3) Capture d’écran du résumé console (répartition par pays et par fournisseur).
4) Mini README (≤ 1 page) :
 - Comment créer l’environnement venv et installer les libs
 - Commande pour lancer le script
 - Description du CSV
 - Exemples d’IP utilisées pour les tests

----------------------------------------------------------------------------------
8) Barème (20 points)
----------------------------------------------------------------------------------
- Lecture du fichier d’IP et appels API ......................... 5 pts
- Extraction des données utiles (JSON → dict) .................. 5 pts
- Classement et résumé en console ............................... 4 pts
- Génération CSV propre ......................................... 4 pts
- README / qualité globale ...................................... 2 pts

----------------------------------------------------------------------------------
9) Bonus (facultatif)
----------------------------------------------------------------------------------
- Détecter automatiquement IP privées / locales et les ignorer.
- Ajouter une option CLI pour filtrer par pays ou fournisseur.
- Générer un graphique simple (bar chart par pays avec matplotlib).
- Compter le % d’IP de type “datacenter” vs “résidentiel”.