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

En-tête d'authentification (remplacez VOTRE_CLE par la clé qui vous est délivrée) :

en-tête

Authorization: Bearer VOTRE_CLE

Aucune clé publique : l'accès est accordé sur demande à [email protected].

clé commune

slug de race

Même identifiant dans l'API et les datasets.

privacy by design

élevages assainis

Affixe, localisation et races produites, sans téléphone ni email.

contrôles

score qualité

Complétude, unicité, fraîcheur et cohérence documentées.

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 VOTRE_CLE"

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 VOTRE_CLE"

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 VOTRE_CLE"

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 VOTRE_CLE"

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"
}