Régions

Catalogue ISO 3166-2 non borné (~5 300 documents) hébergé dans l’index Meilisearch MEILISEARCH_REGIONS_INDEX (défaut regions). Lecture seule depuis Meili — aucun domaine Region côté MySQL, l’index est alimenté par un processus externe. Contrairement aux pays, le volume impose une pagination obligatoire (les 5 300 entrées ne tiennent pas dans un seul appel raisonnable).

Identité côté API : le id JSON:API d’une ressource regions est le code ISO 3166-2 en minuscules (fr-idf, ad-02, gb-eng, …). Les documents Meili stockent le code en majuscules dans le champ id (FR-IDF, AD-02) — Hydrogen normalise à la sérialisation. Les URLs sont case-insensitive end-to-end (/api/regions/fr-idf ≡ /api/regions/FR-IDF).

Descriptions Markdown : la ressource détail (GET /api/regions/{code}) embarque un attribut description dont la valeur est le contenu brut Markdown du fichier resources/lang/<locale>/regions/<code>/description.md. Le layout est un dossier par région (<code>/) contenant description.md — mêmes propriétés et même fallback que pour les pays. La locale est résolue par LocaleResolverMiddleware (header Accept-Language ou param). Si le fichier n’existe pas pour la locale courante, fallback sur la locale SupportedLocales::DEFAULT ; si aucune des deux n’existe, description = null (la région sert quand même, juste sans blurb). Le Markdown n’est pas rendu côté serveur.

Bloc country inline : chaque ressource regions (listing, search, détail) embarque un attribut country qui est un sous-ensemble léger du document pays parent — assez d’info pour afficher “Île-de-France · France · Europe” sans nécessiter un appel à /api/countries/<code>. Champs exposés : id (ISO alpha-2 minuscule, ex: fr), name, slug, continent, continentId. Pour la description longue, la liste des fuseaux ou les official_name multi-locales, appeler /api/countries/<code>. Le bloc résout en un seul appel Meili sur l’index countries par requête (batch-loader request-scoped), peu importe le nombre de hits. Si le country_id d’une région est manquant ou ne résout pas (code orphelin), country = null.

Garde anti-path-traversal : le code passe par une regex ^[a-z0-9-]{2,7}$ avant toute lecture disque. Toute tentative d’injection court-circuite la résolution → description = null.

GET /api/regions

Listing paginé du catalogue, avec filtre optionnel par pays.

• Auth : aucune.

• Action : ListRegionsAction.

• Query :

  • limit (int, défaut 20, plafond 100).
  • offset (int ≥ 0, défaut 0).
  • country (string, optionnel) — code ISO 3166-1 alpha-2 (2 lettres, case-insensitive). Filtre Meili exact sur country_id. Format invalide → 422 Invalid country code.

• Pas de description dans le listing : charger des milliers de fichiers Markdown sur un endpoint de catalogue est gaspilleur. Le blurb n’est disponible que sur le détail.

• Réponse 200 OK :

{
  "data": [
    {
      "type": "regions",
      "id":   "fr-idf",
      "attributes": {
        "name": "Île-de-France",
        "slug": "ile-de-france",
        "type": "Région",
        "codes": { "osm": "8649", "wikidata": "Q13917", "wikipedia": "fr:Île-de-France" },
        "names": { "fr-FR": "Île-de-France", "en-US": "Île-de-France" },
        "native_name": "Île-de-France",
        "alt_names": null,
        "official_names": null,
        "country_id": "FR",
        "stats": { "stats": null, "surface": "12011.4" },
        "latitude": 48.85,
        "longitude": 2.35,
        "country": {
          "id":          "fr",
          "name":        "France",
          "slug":        "france",
          "continent":   "Europe",
          "continentId": "EU"
        }
      }
    }
  ],
  "links": {
    "self":  "https://api.example/api/regions?country=fr&limit=20",
    "first": "https://api.example/api/regions?country=fr&limit=20",
    "prev":  null,
    "next":  "https://api.example/api/regions?country=fr&limit=20&offset=20",
    "last":  "https://api.example/api/regions?country=fr&limit=20&offset=0"
  },
  "meta": {
    "totalHits": 18,
    "limit":     20,
    "offset":    0,
    "count":     18,
    "country":   "FR"
  }
}

• Réponses d’erreur :
  • 422 Invalid country code — country ne matche pas la regex [a-zA-Z]{2}.
  • 503 Search backend unavailable.

GET /api/regions/search

Trois modes combinables :

1. Full-text : ?q=<term>.
2. Geo-rayon : ?lat=&lng=&distance= (mètres) — les trois ensemble, sinon 422.
3. Filtre pays : ?country=FR — combinable avec n’importe quel autre mode.

• Auth : aucune.

• Action : SearchRegionsAction.

• Query :

  • q (string, optionnel) — recherche full-text.
  • lat (float [-90, 90]), lng (float [-180, 180]), distance (int positif, mètres) — tous trois requis ensemble pour le mode géo, sinon 422 Incomplete geo parameters.
  • country (string, optionnel) — ISO 3166-1 alpha-2.
  • limit (int, défaut 20, plafond 50).
  • offset (int ≥ 0, défaut 0).

• Plafond distance : REGION_NEARBY_MAX_DISTANCE_METERS (défaut 2 000 000 m = 2 000 km). Dépassement → 422 Distance too large.

• Tri géo : en mode géo, tri par _geoPoint(lat, lng):asc (distance croissante). En mode full-text pur, tri par pertinence Meili. Pré-requis ops : _geo dans sortableAttributes de l’index regions (NON activé par défaut sur le déploiement, voir bloc Pré-requis en fin de section).

• Réponse 200 OK :

{
  "data": [
    {
      "type": "regions",
      "id":   "fr-idf",
      "attributes": {
        "name":       "Île-de-France",
        "country_id": "FR",
        "country":    { "id": "fr", "name": "France", "slug": "france", "continent": "Europe", "continentId": "EU" },
        "...":        "..."
      }
    }
  ],
  "links": {
    "self":  "https://api.example/api/regions/search?q=ile",
    "first": "https://api.example/api/regions/search?q=ile&limit=20",
    "prev":  null,
    "next":  null,
    "last":  null
  },
  "meta": {
    "totalHits": 4,
    "limit":     20,
    "offset":    0,
    "query":     "ile",
    "country":   "FR",
    "center":    { "lat": 48.85, "lng": 2.35 },
    "distance":  500000
  }
}

country, center et distance ne sont présents que quand le mode correspondant est actif.

• Réponses d’erreur :
  • 422 Invalid country code — country mal formé.
  • 422 Incomplete geo parameters — un des lat/lng/distance fourni mais pas les autres.
  • 422 Invalid latitude / Invalid longitude / Invalid distance — valeurs hors bornes ou non numériques.
  • 422 Distance too large — distance > REGION_NEARBY_MAX_DISTANCE_METERS.
  • 503 Search backend unavailable.

GET /api/regions/{code}

Détail d’une région par son code ISO 3166-2 (2 à 7 caractères, case-insensitive). Filtre Meili exact sur id = "<UPPER>" — pas de recherche full-text (le scorer pourrait surfacer la mauvaise subdivision sur des codes de bord).

• Auth : aucune.

• Action : GetRegionAction.

• Path :

  • {code} — regex [a-zA-Z0-9-]{2,7} (accepte XX, XX-YYY, XX-99, …). Casse normalisée à la résolution (majuscules pour Meili, minuscules pour le id JSON:API). Format invalide → 404.

• Différence clé avec le listing : ajoute un attribut description chargé depuis resources/lang/<locale>/regions/<code>/description.md (voir intro de section).

• Réponse 200 OK (locale fr-FR) :

{
  "data": {
    "type": "regions",
    "id":   "fr-idf",
    "attributes": {
      "name":           "Île-de-France",
      "slug":           "ile-de-france",
      "type":           "Région",
      "codes":          { "osm": "8649", "wikidata": "Q13917", "wikipedia": "fr:Île-de-France" },
      "names":          { "fr-FR": "Île-de-France", "en-US": "Île-de-France" },
      "native_name":    "Île-de-France",
      "alt_names":      null,
      "official_names": null,
      "country_id":     "FR",
      "stats":          { "stats": null, "surface": "12011.4" },
      "latitude":       48.85,
      "longitude":      2.35,
      "country":        { "id": "fr", "name": "France", "slug": "france", "continent": "Europe", "continentId": "EU" },
      "description":    "# Île-de-France\n\nL'**Île-de-France** est la région la plus peuplée…"
    }
  }
}

• Réponses d’erreur :
  • 404 Region not found — code invalide (regex non matchée) OU code valide mais aucun document Meili correspondant.
  • 503 Search backend unavailable.

Pré-requis index Meilisearch (one-shot ops) :

• id dans filterableAttributes (pour le lookup exact du détail) — déjà actif.
• country_id dans filterableAttributes (pour le filtre ?country=) — déjà actif.
• _geo dans filterableAttributes (pour ?lat=&lng=&distance=) — déjà actif.
• _geo dans sortableAttributes (pour trier par distance dans le mode géo) — NON activé par défaut ; sans lui, le filtre _geoRadius(...) fonctionne mais le tri par distance retombe sur l’ordre de pertinence Meili.
• les champs texte recherchables dans searchableAttributes (* couvre tout sur le déploiement courant).

---