watch-api

Liveness check. Le seul endpoint sans authentification.

curl https://watch-api-ochre.vercel.app/api/health

{ "ok": true }

Recherche par texte sur marque / modèle / référence. Renvoie une liste de résultats légers.

curl -H "x-api-key: <clé>" \
  "https://watch-api-ochre.vercel.app/api/watches/search?q=submariner&limit=5"

[
  {
    "id": "clx0abc123",
    "name": "Submariner Date",
    "brand": "Rolex",
    "year": 2020,
    "imageUrl": "https://.../submariner.jpg",
    "model": "Submariner Date",
    "reference": "126610LN"
  }
]

• Les clés id, name, brand, year, imageUrl sont identiques au payload de détail (même id, mêmes noms).
• model et reference sont fournis en champs supplémentaires pour l'affichage.

Fiche complète d'une montre — le payload qui alimente chaque écran de jeu.

curl -H "x-api-key: <clé>" \
  https://watch-api-ochre.vercel.app/api/watches/clx0abc123

{
  "id": "clx0abc123",
  "name": "Submariner Date",
  "brand": "Rolex",
  "brandLogoUrl": "https://.../rolex-logo.svg",
  "year": 2020,
  "imageUrl": "https://.../cover.jpg",
  "images": ["https://.../cover.jpg", "https://.../side.jpg"],
  "collection": "Submariner",
  "reference": "126610LN",
  "nickname": null,
  "country": "Suisse",
  "movement": "Automatique",
  "caliber": "Rolex 3235",
  "caseMaterial": "Acier",
  "braceletMaterial": "Acier",
  "caseDiameterMm": 41,
  "caseDimensions": null,
  "variants": [],
  "caliberExecutions": [],
  "technicalDataTruncated": false,
  "complications": ["Date"],
  "priceTier": "5-20k€",
  "gender": "Homme",
  "famous": true,
  "imageCredit": null,
  "model": "Submariner Date",
  "diameter": 41
}

• Tout champ sauf id, name et brand peut être null (ou []).
• model et diameter sont des alias hérités de name et caseDiameterMm.
• caseDimensions contient, lorsqu'elles sont sourcées, diameterMm, widthMm, lengthMm et thicknessMm sous forme de chaînes décimales exactes ; elles ne remplacent pas le diamètre entier historique. Chaque variant peut porter ses propres caseDimensions. caliberExecutions relie une Watch ou Variant à une exécution conditionnelle et à son calibre partagé. La réponse détail borne ces listes à 200 et indique technicalDataTruncated.
• brandLogoUrl est le logo de la marque (Wikimedia, licence libre) ; null pour les marques sans logo libre ou les fiches non encore reliées à leur marque.
• complications relève de la curation éditoriale (aucune source importée ne la fournit) : la couverture est encore partielle et se remplit au fil de l'enrichissement. Attendez-vous à [] sur une part des fiches.
• imageUrl / images sont des liens externes (jamais ré-hébergés) accompagnés de leur crédit et licence ; la couverture photo est encore partielle et progresse au fil de l'enrichissement. Prévoyez un rendu sans image.
• 404 { "error": "not_found" } si l'id n'existe pas.
• Non encore sourcés (absents du payload, ajoutés plus tard) : priceEur, waterResistanceM, productionYears. Utilisez priceTier comme signal de prix.

Tire une ou plusieurs montres du catalogue. Sert la « montre du jour » de façon déterministe, sans état côté serveur.

# Montre du jour déterministe depuis le pool famous
curl -H "x-api-key: <clé>" \
  "https://watch-api-ochre.vercel.app/api/watches/random?famous=true&date=2026-07-24"

# Cinq montres famous distinctes
curl -H "x-api-key: <clé>" \
  "https://watch-api-ochre.vercel.app/api/watches/random?famous=true&count=5"

// Même forme que GET /api/watches/:id
// (objet unique, ou tableau si count est fourni)

• 404 { "error": "empty_pool" } uniquement si le catalogue est réellement vide.
• Le « ne pas répéter pendant N jours » est à la charge du consommateur — l'API ne fait que le tirage.

Origine des faits d'une fiche : quelle observation gagnante (source + tier de confiance) sous-tend chaque champ.

curl -H "x-api-key: <clé>" \
  https://watch-api-ochre.vercel.app/api/watches/clx0abc123/provenance

// Par champ : la valeur retenue et la source qui l'a emporté
// à l'arbitrage (voir « verified » / tier de confiance).

Liste des marques du catalogue (haut de la hiérarchie Brand → Collection → Model → Watch), avec logo, histoire et compteurs.

curl -H "x-api-key: <clé>" https://watch-api-ochre.vercel.app/api/brands

[
  {
    "id": "clbrand01",
    "key": "rolex",
    "name": "Rolex",
    "country": "Suisse",
    "logoUrl": "https://.../rolex-logo.svg",
    "description": "Manufacture genevoise fondée en 1905…",
    "foundedYear": 1905,
    "models": 57,
    "collections": 18,
    "references": 1240
  }
]

• logoUrl, description et foundedYear proviennent de la curation éditoriale ; ils peuvent être null (ex. marque sans logo sous licence libre).
• models / collections / references sont les compteurs de la marque dans le catalogue.

Détail d'un modèle et ses références (le niveau que la plupart du contenu externe adresse).

curl -H "x-api-key: <clé>" https://watch-api-ochre.vercel.app/api/models/<model-id>

// Fiche modèle + ses watches/références

Les montres équipées d'un calibre donné (ex. Rolex 3235).

curl -H "x-api-key: <clé>" https://watch-api-ochre.vercel.app/api/calibers/<key>/watches

// Tableau de montres partageant ce calibre