Documentation API
Import d'alertes de déforestation

API pour l'importation de données géospatiales [geojson] des zones de déforestation dans le système gestion des alertes (SNSF)

v1.0.2

Vue d'ensemble

Cette API permet l'importation de données géospatiales représentant des alertes de déforestation. Elle accepte des fichiers au format GeoJSON et les transforme en alertes stockées dans le système.

📊

Fonctionnalités clés

  • Import de fichiers GeoJSON
  • Validation des données géospatiales
  • Détection automatique des doublons
  • Génération de rapports détaillés
⚡

Performances

  • Traitement par lots optimisé
  • Validation en temps réel
  • Réponses immédiates avec statut
🔒

Sécurité

  • Authentification JWT obligatoire
  • Validation stricte des entrées
  • Limites de taille des fichiers

Cette API est conçue pour traiter des données géospatiales de déforestation provenant du modèle IA intégrée et autres sources avérées. Elle effectue automatiquement les validations nécessaires et fournit un retour détaillé sur le processus d'importation. Veillez-vosu réferer aux conditions d'utilisation pour une mieux prise en main

Points d'accès

POST /api/alertes/importer/

Endpoint principal pour l'importation d'alertes de déforestation au format GeoJSON.

Paramètres

Paramètre Type Obligatoire Description
geojson Fichier Oui Fichier GeoJSON contenant les alertes à importer (max 50MB)
source String Non Source des données (par défaut: "data354")

Authentification

L'accès à cet endpoint nécessite une authentification via JWT Token dans le header Authorization :

Header d'authentification 
Authorization: Bearer votre_token_jwt

Les requêtes non authentifiées ou avec un token invalide seront rejetées avec un code HTTP 401. Assurez-vous que votre token est valide et non expiré.

Format de requête

L'API accepte les requêtes au format multipart/form-data avec les paramètres décrits ci-dessus.

Exemple de requête complète

Requête HTTP
POST /api/alertes/import/ HTTP/1.1
Host: votre-domaine.com
Authorization: Bearer votre_token_jwt
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="geojson"; filename="alertes.geojson"
Content-Type: application/geo+json

<contenu du fichier GeoJSON>
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="source"

data354
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Bonnes pratiques

  • Utilisez toujours le Content-Type multipart/form-data pour les requêtes
  • Spécifiez le nom du fichier dans le header Content-Disposition
  • Pour les gros fichiers, envisagez une compression GZIP
  • Limitez la taille des fichiers à 50MB maximum

Format GeoJSON attendu

L'API attend un fichier GeoJSON valide conforme à la spécification RFC 7946, avec des exigences supplémentaires pour les propriétés.

Structure GeoJSON minimale requise
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-4.130860019550161, 5.705299301969915],
            [-4.130860019550161, 5.789104511063385],
            [-4.032562180312707, 5.789104511063385],
            [-4.032562180312707, 5.705299301969915],
            [-4.130860019550161, 5.705299301969915]
          ]
        ]
      },

      "properties": {
        "area_ha": 12.5,
        "date": "2025-05-09T12:00:00Z"
      }
    }
  ]
}

Exigences de validation

Élément Validation Message d'erreur
Type racine Doit être "FeatureCollection" "Type GeoJSON invalide: doit être FeatureCollection"
Tableau features Doit exister et contenir au moins un élément "Aucune feature trouvée dans le GeoJSON"
Type feature Chaque élément doit être de type "Feature" "Feature invalide: type incorrect"
Géométrie Doit être un Polygon valide (fermé) "Géométrie invalide: doit être un Polygon"
Propriété date Doit exister et être au format Format ISO 8601 "Propriété date manquante ou invalide"

Types de réponses

L'API retourne toujours des réponses au format JSON avec un code HTTP approprié. Voici les différents cas possibles :

Succès complet (HTTP 201)

Réponse de succès
{
  "status": "success",
  "message": "Import réussi : 42/42 zones enregistrées",
  "nb importés": 42,
  "nb doublons": 0,
  "rapport": "rapport_20250509_152230.txt",
  "timestamp": "2025-05-09T15:22:30Z"
}

Succès partiel (HTTP 207)

Réponse de succès partiel
{
  "status": "partial_success",
  "message": "38/42 zones enregistrées, 4 erreurs",
  "nb importés": 38,
  "nb erreurs": 4,
  "nb doublons": 2,
  "rapport": "rapport_20250509_152545.txt",
  "timestamp": "2025-05-09T15:25:45Z",
  "erreurs": [
    {
      "id": "feature_123",
      "erreur": "Polygone déjà existant",
      "type": "duplicate"
    },
    {
      "id": "feature_456",
      "erreur": "Propriété area_ha manquante",
      "type": "validation"
    }
  ]
}

Échec de validation (HTTP 400)

Réponse d'erreur de validation
{
  "error": "Format GeoJSON invalide",
  "details": "La propriété 'features' est manquante ou n'est pas un tableau",
  "timestamp": "2025-05-09T15:27:12Z"
}

Codes d'erreurs

L'API utilise les codes HTTP standard pour indiquer le statut des requêtes :

Code Description Correction possible
201 Création réussie - Toutes les alertes importées -
207 Multi-Status - Certaines alertes importées, d'autres échouées Vérifiez les erreurs dans la réponse
400 Requête incorrecte - Format GeoJSON invalide Validez votre fichier GeoJSON
401 Non autorisé - Token JWT manquant ou invalide Vérifiez votre authentification
413 Payload trop large - Fichier > 50MB Divisez votre fichier en lots plus petits
500 Erreur serveur - Problème interne Contactez le support technique

En cas d'erreur 500, un identifiant unique de l'erreur est inclus dans la réponse pour faciliter le débogage avec l'équipe technique.

Validations appliquées

L'API effectue plusieurs niveaux de validation sur les données reçues :

1. Validation du format GeoJSON

  • Structure JSON valide
  • Type racine = FeatureCollection
  • Présence du tableau features
  • Chaque feature doit avoir une géométrie et des propriétés

2. Validation des géométries

  • Type de géométrie = Polygon
  • Coordonnées valides (WGS84)
  • Polygone fermé (premier point = dernier point)
  • Superficie minimale de 0.05 ha

3. Validation des propriétés

  • Propriété date obligatoire
  • Format ISO 8601 pour la date
  • Valeur numérique positive pour area_ha
  • Pas de doublon exact (même géométrie et superficie)

Les polygones auto-intersectants ou trop complexes (plus de 1000 sommets) peuvent être rejetés ou simplifiés automatiquement.

Exemples complets

Exemple avec cURL

Import avec cURL
curl -X POST \
  https://snssf.onrender.com/api/alertes/importer \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "geojson=@chemin/vers/alertes_yappo_abbe.geojson" \
  -F "source=data354"

Exemple avec Python

Script Python complet
import requests
import json

# Configuration
API_URL = "https://snssf.onrender.com/api/alertes/importer"
TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
GEOJSON_FILE = "alerts_20250509.geojson"

# Vérification préalable du fichier
try:
    with open(GEOJSON_FILE) as f:
        geojson_data = json.load(f)
        print(f"Fichier valide contenant {len(geojson_data['features'])} features")
except Exception as e:
    print(f"Erreur dans le fichier GeoJSON: {str(e)}")
    exit(1)

# Envoi à l'API
try:
    with open(GEOJSON_FILE, 'rb') as f:
        response = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {TOKEN}"},
            files={"geojson": (GEOJSON_FILE, f, "application/geo+json")},
            data={"source": "data354"}
        )
        
        if response.status_code == 201:
            print("Succès! Toutes les alertes ont été importées")
        elif response.status_code == 207:
            result = response.json()
            print(f"Succès partiel: {result['nb importés']} importées, {result['nb erreurs']} erreurs")
            for err in result.get("erreurs", []):
                print(f"- {err['id']}: {err['erreur']}")
        else:
            print(f"Erreur {response.status_code}: {response.json().get('error')}")
            
except requests.exceptions.RequestException as e:
    print(f"Erreur de connexion: {str(e)}")

Limites techniques

📏

Tailles maximales

  • Fichier GeoJSON: 50MB
  • Nombre de features par requête: 1000
  • Sommets par polygone: 1000
⏱️

Performances

  • Temps de traitement moyen: 2ms/feature
  • Délai maximal: 30 secondes
  • Débit recommandé: 500 features/requête
🔄

Fréquence

  • 10 requêtes/minute
  • 5000 features/minute
  • Quota mensuel: 1M features

Pour des imports massifs (>10k features), contactez-nous pour obtenir un accès spécial et des quotas étendus.

Notes techniques avancées

Traitement des géométries

Les polygones subissent plusieurs transformations automatiques :

  1. Conversion en MultiPolygon pour uniformité
  2. Simplification si trop de sommets (algorithme Douglas-Peucker)
  3. Calcul de l'aire réelle (en cas de divergence avec area_ha > 10%)
  4. Calcul du centroïde pour l'indexation spatiale

Gestion des doublons

La détection des doublons utilise une comparaison spatiale avec une tolérance de 1m :

  • Même emplacement (intersection à 99%)
  • Même date de génération (±1 jour)
  • Superficie similaire (±5%)

Journalisation

Toutes les requêtes sont journalisées avec :

  • Timestamp de la requête
  • Identifiant utilisateur
  • Nombre de features traitées
  • Statut final
  • Hash du fichier pour suivi

Rapport d'importation

Un rapport détaillé est généré pour chaque importation et contient :

Exemple de rapport
=== RAPPORT D'IMPORTATION ===
Date: 2025-05-09 15:22:30 UTC
Fichier: alerts_20250509.geojson (SHA-256: a1b2c3...)
Source: data354
Utilisateur: salomon123@data354.com

=== STATISTIQUES ===
Features totales: 42
Import réussis: 38 (90.5%)
Doublons détectés: 2 (4.8%)
Erreurs de validation: 2 (4.8%)

=== ERREURS DÉTAILLÉES ===
1. Feature ID: alert_789
   - Type: Validation
   - Erreur: Propriété area_ha manquante
   - Emplacement: [-52.123, -3.456]

2. Feature ID: alert_456
   - Type: Duplicata
   - Emplacement existant: [-52.215, -3.457]
   - Date existante: 2025-05-08

=== METADONNÉES ===
Temps de traitement: 1.2s
Taille fichier: 245KB
Version API: v1.0
ID Requête: req_a1b2c3d4e5

Accès aux rapports

Les rapports sont disponibles pendant 30 jours via :

  • L'URL retournée dans la réponse JSON
  • L'interface utilisateur du portail
  • L'API de téléchargement avec l'ID de requête