Le projet est modulaire et basé sur le framework FastAPI. Voici la structure globale :
osm-trip-api/
├── app/
│ ├── main.py (Initialisation FastAPI + endpoints de base)
│ ├── config.py (Paramètres et environnement)
│ ├── auth.py (Gestion de l'authentification API key)
│ ├── cache.py (Mise en cache via TTL pour Wikidata, etc.)
│ ├── catalog.py (Taxonomie des POIs)
│ │
│ ├── core/ (Utilitaires métiers)
│ │ ├── http.py (Clients HTTP avec gestion d'auth interne)
│ │ ├── quota.py (Gestion des quotas journaliers par provider)
│ │ └── response_builder.py
│ │
│ ├── providers/ (Connecteurs aux APIs externes)
│ │ ├── osm/ (Overpass, Nominatim, Polygon)
│ │ ├── wikidata/ (Enrichissement structuré)
│ │ ├── wikipedia/ (Enrichissement textuel)
│ │ └── (google, mapbox, opencage, geoapify, geonames...)
│ │
│ └── routers/ (Séparation des routes par domaine)
│ ├── places_discovery.py
│ ├── places_batch.py
│ ├── stats.py
│ └── (Fournisseurs spécifiques : google.py, mapbox.py...)
│
├── tests/ (Suite de tests unitaires et intégration)
├── pyproject.toml (Configuration du package)
└── start.sh / start.bat (Scripts de lancement)
L'architecture s'appuie sur les APIRouter de FastAPI, ce qui permet de diviser le code par domaine (ex: places_discovery, stats). Chaque module de routeur s'enregistre ensuite dans le fichier principal main.py.
verify_api_key (via Dependency Injection)/health, /catalog, /kinds/places/search, /places/bbox, /places/radius, /places/{xid}/places/nearby, /places/autocomplete/places/batch/stats, /health/detailed