# 🏆 Trails NY — Module Pulse

> Base de sentiers randonnée & trail running pour la région de New York.
> Alimentée par des APIs publiques, gratuites, sans scraping.
> Conçue pour s'intégrer à la couche sociale Pulse (segments, défis, export GPX).

## Architecture

```
trails-ny/
├── src/
│   ├── overpass_poc.py      # Overpass API → sentiers OSM avec géométrie GPS
│   ├── usgs_elevation.py    # Open-Elevation → profils d'élévation
│   ├── noaa_weather.py      # NOAA/NWS → météo temps réel par sentier
│   └── run.py               # Pipeline complet
├── data/
│   ├── trails_meta.json     # ~900 sentiers Harriman/Bear Mtn (tags + IDs)
│   ├── trails_geom.json     # ~10 sentiers avec géométrie détaillée
│   ├── trail_elevation.json # Profils d'élévation
│   └── trail_weather.json   # Prévisions NOAA
└── README.md
```

## APIs utilisées

### 1. 🌲 OpenStreetMap — Overpass API
- **Endpoint:** `https://overpass-api.de/api/interpreter`
- **Données:** Traces GPS de sentiers (ways), tags (surface, operator, sac_scale)
- **Quota:** Généreux, 2 requêtes/s en moyenne
- **Résolution:** Métrique (tracés OSM, précision 1-10m selon le sentier)
- **Coût:** Gratuit
- **Alternatives:** Instance Overpass Kumi, Overpass Turbo

**Différenciation AllTrails:** On ne scrape pas AllTrails. On pioche direct dans OSM — les mêmes données map que Strava, Komoot, GaiaGPS. Tags qu'AllTrails cache : `surface`, `sac_scale`, `trail_visibility`, `operator` (NY-NJ Trail Conference, JORBA, etc.)

### 2. ⛰️ Open-Elevation (SRTM / GETASSE30)
- **Endpoint:** `https://api.open-elevation.com/api/v1/lookup`
- **Données:** Élévation en mètres, résolution ~30m
- **Quota:** Généreux, pas de clé nécessaire
- **Coût:** Gratuit
- **Amélioration possible:** USGS 3DEP (1/3 arc-sec ≈ 10m) avec clé API

**Usage:** Profil d'élévation complet par sentier → dénivelé+, pente max, graphique.

### 3. 🌤️ NOAA — National Weather Service API
- **Endpoint:** `https://api.weather.gov/points/{lat},{lon}`
- **Données:** Prévisions 7 jours (température, vent, précipitations, humidité)
- **Quota:** Généreux, pas de clé, rate limit standard
- **Résolution:** Grille 2.5km (la meilleure grille publique US)
- **Coût:** Gratuit
- **Données uniques:** "Areas of Smoke" (incendies), alertes météo, hourly forecast

## Résultats PoC (Harriman State Park)

| Métrique | Valeur |
|---|---|
| Sentiers récupérés | **871** (358 nommés) |
| Opérateur principal | **NY-NJ Trail Conference** (156 sentiers) |
| Surface dominante | ground (665), dirt (212), unpaved (89) |
| Appalachian Trail (section) | 255→368m, +249m gain |
| Météo temps réel | OKX 28/68 grille, Woodbury NY |

## Différenciation vs AllTrails (rappel)

| AllTrails | Trails NY |
|---|---|
| Carte monde générique | **Hyper-local NY** (Hudson Valley, Catskills, Harriman) |
| Pas de couche sociale Pulse | **Intégré** à Pulse (segments, défis, GPX) |
| Données fermées | **Open Data** (OSM + NOAA + Elevation) |
| Payant | **Gratuit** (APIs publiques) |
| Tags cachés | Surface, sac_scale, opérateur visibles |
| Pas de météo embarquée | **NOAA temps réel** sur chaque sentier |

## Next steps

1. **Étendre la zone** — Catskills, Breakneck Ridge, Palisades, Hudson Highlands
2. **Index spatial** — PostGIS ou DuckDB spatial pour requêtes rapides (sentier le plus proche, recherche par difficulté)
3. **Profils avancés** — Pente segmentée, temps estimé (Naismith), surface analysis
4. **Couche sociale** — Segments Strava-like, défis entre amis, classements
5. **Export GPX** — Génération fichier GPX depuis géométrie OSM
6. **Carte interactive** — Leaflet/MapLibre avec tracés OSM + couches météo