Référence API v1

API REST en lecture seule. Base : https://canidata.fr/api/v1. Réponses JSON. Authentification par clé (voir authentification).

REST JSON CORS * 1000 req / h

Clé démo publique, prête à copier :

en-tête

Authorization: Bearer cani_demo_public_2026

GET /api/v1/breeds

Liste paginée des races, avec recherche, filtre de popularité et tri.

Paramètre	Type	Défaut	Description
q	string	—	Recherche sur le nom de la race.
tier	integer	—	Popularité (1 = top … 4 = niche).
sort	enum	breeders	breeders \| name \| tier
page	integer	1	Numéro de page.
limit	integer	20	Éléments par page (max 100).

requête

curl -s "https://canidata.fr/api/v1/breeds?q=berger&limit=2" \
  -H "Authorization: Bearer cani_demo_public_2026"

réponse 200

{
  "data": [
    {
      "slug": "berger-australien",
      "name": "Berger Australien",
      "popularity_tier": 1,
      "stats": { "breeders": 1307, "lof": 1303, "puppies_available": 7 },
      "links": { "self": "/api/v1/breeds/berger-australien" }
    }
  ],
  "meta": { "pagination": { "page": 1, "limit": 2, "total": 38 } }
}

GET /api/v1/breeds/{slug}

Détail d'une race et un échantillon de 10 élevages référencés.

Paramètre	Type	Défaut	Description
slug	string	—	Identifiant de la race (chemin).

requête

curl -s "https://canidata.fr/api/v1/breeds/golden-retriever" \
  -H "Authorization: Bearer cani_demo_public_2026"

réponse 200

{
  "data": {
    "slug": "golden-retriever",
    "name": "Golden Retriever",
    "stats": { "breeders": 836, "lof": 825, "puppies_available": 16 },
    "sample_breeders": [
      { "name": "VALLEY", "location": { "region": "Bretagne" }, "lof": true }
    ]
  }
}

GET /api/v1/breeders

Annuaire assaini des élevages. Filtres combinables. Aucune coordonnée de contact.

Paramètre	Type	Défaut	Description
breed	slug	—	Élevages produisant cette race.
department	string	—	Code département (ex. 56, 2A).
region	slug	—	Région normalisée (ex. bretagne).
lof	boolean	—	1 → uniquement les élevages LOF.
puppies	boolean	—	1 → uniquement avec chiots dispo.
q	string	—	Recherche sur le nom d'élevage.

requête

curl -s "https://canidata.fr/api/v1/breeders?breed=golden-retriever&region=bretagne&lof=1" \
  -H "Authorization: Bearer cani_demo_public_2026"

réponse 200

{
  "data": [
    {
      "name": "Always Hope",
      "location": { "city": "PLOUGUENAST", "department": "22", "region": "Bretagne" },
      "races": ["golden-retriever"],
      "lof": true,
      "puppies_available": false,
      "geo": { "lat": 48.28, "lng": -2.70 }
    }
  ],
  "meta": { "pagination": { "page": 1, "limit": 20, "total": 17 } }
}

GET /api/v1/stats

Totaux plateforme, ventilation par région et top 15 des races.

requête

curl -s "https://canidata.fr/api/v1/stats" \
  -H "Authorization: Bearer cani_demo_public_2026"

réponse 200

{
  "data": {
    "totals": { "breeds": 502, "breeders": 19754, "lof": 19374 },
    "by_region": [
      { "region": "Nouvelle-Aquitaine", "breeders": 2541, "lof": 2512 }
    ],
    "top_breeds": [
      { "slug": "berger-australien", "name": "Berger Australien", "breeders": 1307 }
    ]
  }
}

GET /api/v1/status public

Santé de la plateforme et fraîcheur des données. Sans authentification.

requête

curl -s "https://canidata.fr/api/v1/status"

réponse 200

{
  "status": "operational",
  "database": "ok",
  "snapshot_date": "2026-06-26",
  "volumetry": { "breeds": 502, "breeders": 19754, "regions": 13 },
  "license": "CC BY 4.0"
}