Guide d'intégration - Application Symfony

Ce document décrit la compatibilité de notre API avec les besoins spécifiques de l'application Symfony.

✅ Endpoints requis par l'application Symfony

Tous les endpoints utilisés par l'application Symfony sont 100% compatibles.

1. Détails d'une commune par code INSEE

Endpoint : GET /communes/{code}

Exemple utilisé :

bash

curl "https://2mnservices.alwaysdata.net/communes/21231?fields=nom,codeDepartement,codeRegion,codesPostaux,centre,population,surface"

Réponse attendue :

json

{
  "nom": "Auxonne",
  "code": "21231",
  "codeDepartement": "21",
  "codeRegion": "27",
  "codesPostaux": ["21130"],
  "centre": {
    "type": "Point",
    "coordinates": [5.3872, 47.1944]
  },
  "population": 7256,
  "surface": 40.65
}

Utilisé dans :

CityDataService.php:97
ApiHealthMonitor.php:33

Statut : ✅ FONCTIONNEL

2. Recherche de communes par nom

Endpoint : GET /communes?nom={nom}&fields=...

Exemple utilisé :

bash

curl "https://2mnservices.alwaysdata.net/communes?nom=Paris&fields=code,nom,codeDepartement,codeRegion,codesPostaux,centre,population,surface&boost=population&limit=1"

Réponse attendue :

json

[
  {
    "code": "75056",
    "nom": "Paris",
    "codeDepartement": "75",
    "codeRegion": "11",
    "codesPostaux": ["75001", "75002", "75003", "75004", "75005", "75006", "75007", "75008", "75009", "75010", "75011", "75012", "75013", "75014", "75015", "75016", "75017", "75018", "75019", "75020"],
    "centre": {
      "type": "Point",
      "coordinates": [2.347, 48.859]
    },
    "population": 2103778,
    "surface": 105.4
  }
]

Utilisé dans :

FrenchGeoService.php:24

Statut : ✅ FONCTIONNEL

3. Liste des communes d'un département

Endpoint : GET /departements/{code}/communes

Exemple utilisé :

bash

curl "https://2mnservices.alwaysdata.net/departements/83/communes"

Réponse attendue :

json

[
  {
    "code": "83000",
    "nom": "Toulon",
    "codesPostaux": ["83000"]
  },
  {
    "code": "83001",
    "nom": "La Garde",
    "codesPostaux": ["83130"]
  }
]

Utilisé dans :

SiteMapsController.php:88
SiteMapsController.php:291

Statut : ✅ FONCTIONNEL

4. Détails d'un département

Endpoint : GET /departements/{code}?fields=code,nom,codeRegion,region

Exemple utilisé :

bash

curl "https://2mnservices.alwaysdata.net/departements/83?fields=code,nom,codeRegion,region"

Réponse attendue :

json

{
  "code": "83",
  "nom": "Var",
  "codeRegion": "93",
  "region": {
    "code": "93",
    "nom": "Provence-Alpes-Côte d'Azur"
  }
}

Utilisé dans :

FrenchGeoService.php:76

Statut : ✅ FONCTIONNEL

5. Détails d'une région

Endpoint : GET /regions/{code}?fields=code,nom

Exemple utilisé :

bash

curl "https://2mnservices.alwaysdata.net/regions/93?fields=code,nom"

Réponse attendue :

json

{
  "code": "93",
  "nom": "Provence-Alpes-Côte d'Azur"
}

Utilisé dans :

FrenchGeoService.php:49

Statut : ✅ FONCTIONNEL

🚀 Commandes pour préparer l'API

1. Importer les données des communes

bash

npm run import:communes

2. Enrichir avec les données complètes

bash

npm run enrich:communes

Cette étape est obligatoire pour obtenir :

Les codes postaux
Les coordonnées GPS (centre)
La population
La surface (superficie)
Les informations de département et région

3. Démarrer l'API

bash

npm start

📝 Configuration dans Symfony

Pour utiliser l'API locale dans votre application Symfony, modifiez votre configuration :

yaml

# config/services.yaml ou .env
parameters:
    # Avant (API officielle)
    # geo_api_url: 'https://geo.api.gouv.fr'
    
    # Après (API locale)
    geo_api_url: 'https://2mnservices.alwaysdata.net'

✅ Validation complète

Tous les appels API utilisés par l'application Symfony sont fonctionnels et testés :

Endpoint	Paramètres	Status
`/communes/{code}`	`fields=nom,codeDepartement,codeRegion,codesPostaux,centre,population,surface`	✅
`/communes?nom=`	`fields=code,nom,...&boost=population&limit=1`	✅
`/departements/{code}/communes`	-	✅
`/departements/{code}`	`fields=code,nom,codeRegion,region`	✅
`/regions/{code}`	`fields=code,nom`	✅

🔍 Tests de validation

Pour vérifier que tout fonctionne avant de déployer :

bash

# Test 1: Commune avec tous les champs requiscurl "https://2mnservices.alwaysdata.net/communes/21231?fields=nom,codeDepartement,codeRegion,codesPostaux,centre,population,surface"

# Test 2: Recherche par nom
curl "https://2mnservices.alwaysdata.net/communes?nom=Paris&fields=code,nom,codeDepartement,codeRegion,codesPostaux,centre,population,surface&boost=population&limit=1"

# Test 3: Communes par département
curl "https://2mnservices.alwaysdata.net/departements/83/communes"

# Test 4: Détails département avec région
curl "https://2mnservices.alwaysdata.net/departements/83?fields=code,nom,codeRegion,region"

# Test 5: Détails région
curl "https://2mnservices.alwaysdata.net/regions/93?fields=code,nom"

Tous ces appels doivent retourner les données attendues par l'application Symfony.

💡 Notes importantes

Cache : L'API met en cache les réponses pendant 1 heure pour des performances optimales
Pas de rate limiting : Contrairement à l'API officielle, il n'y a pas de limite de requêtes
Données synchronisées : Les données sont identiques à l'API officielle geo.api.gouv.fr
Format identique : Vous pouvez remplacer l'URL sans modifier le code Symfony

L'API est prête pour l'utilisation avec votre application Symfony ! 🎉