# Coaster World DATA — API publique v1

Version introduite : **v0.9.0**. Étendue avec le Live en **v0.10.0**.

L'API publique est en lecture seule. Elle expose uniquement les données canoniques de Coaster World DATA et ne permet aucune écriture.

Base locale Laragon :

```text
http://coaster-world-data.test/api/v1
```

## Localisation

Les endpoints acceptent `?locale=fr`, `en`, `de`, `es` ou `it`.
Sans paramètre, l'en-tête `Accept-Language` est utilisé, avec repli sur la langue configurée par le serveur.

## Pagination

Les collections acceptent `?page=` et `?per_page=`.
Valeur par défaut : 25. Maximum : 100.

## Endpoints

```text
GET /api/v1/health
GET /api/v1/search?q=...
GET /api/v1/live/attractions

GET /api/v1/parks
GET /api/v1/parks/{id}
GET /api/v1/parks/{id}/attractions
GET /api/v1/parks/{id}/coasters
GET /api/v1/parks/{id}/pois
GET /api/v1/parks/{id}/live

GET /api/v1/attractions
GET /api/v1/attractions/{id}
GET /api/v1/attractions/{id}/live

GET /api/v1/coasters
GET /api/v1/coasters/{id}

GET /api/v1/pois
GET /api/v1/pois/{id}
```

## Filtres principaux

### Parcs

`q`, `country_code`, `kind`, `status`, `page`, `per_page`.

### Attractions

`q`, `park_id`, `kind`, `status`, `include_coasters`, `page`, `per_page`.

Par défaut, `/attractions` n'inclut pas les coasters afin de préserver la séparation Coaster World. Utiliser `include_coasters=1` si nécessaire.

### Coasters

`q`, `park_id`, `status`, `coaster_type`, `page`, `per_page`.

### POI

`q`, `park_id`, `type`, `status`, `page`, `per_page`.


## Live / temps d’attente

Les endpoints Live exposent le dernier état connu sans masquer les données anciennes. Chaque résultat contient une propriété `freshness` :

- `fresh` : donnée récente ;
- `stale` : donnée ancienne mais encore raisonnablement exploitable ;
- `expired` : dernière donnée connue, trop ancienne pour être considérée actuelle ;
- `unavailable` : aucune donnée connue.

`GET /api/v1/live/attractions` accepte `park_id`, `status`, `freshness`, `page` et `per_page`.

`GET /api/v1/parks/{id}/live` renvoie toutes les attractions du parc, y compris celles qui n’ont encore aucune donnée Live, afin que les clients puissent distinguer explicitement `unavailable` d’une attraction absente.

Le cache HTTP des routes Live est volontairement plus court que celui des données encyclopédiques.

## Données extensibles

Les fiches détaillées exposent :

- `translations` : traductions enregistrées ;
- `aliases` : anciens noms et noms alternatifs ;
- `fields` : valeurs canoniques des champs extensibles ;
- `field_quality` : confiance, statut, validation et date de la valeur canonique.

Les observations brutes, conflits et données fournisseurs ne sont pas exposés par cette API publique.

## Sécurité et charge

- API publique en lecture seule ;
- rate limiting par IP ;
- pagination plafonnée ;
- en-têtes HTTP de cache sur les réponses GET réussies ;
- données supprimées logiquement non retournées par défaut ;
- erreurs API rendues en JSON.

Les limites sont configurables via `.env` avec les variables `CW_DATA_API_*` documentées dans `.env.example`.