🔌 L'API publique

C'est quoi, une API ?

Les pages de ce site sont faites pour être lues par des gens. L'API donne exactement les mêmes informations, mais dans une forme faite pour être lue par un programme : pas de couleurs, pas de mise en page, juste les données. On appelle ce format du JSON — du texte, avec des noms et des valeurs.

Concrètement : vous ouvrez une adresse, et au lieu d'une page, vous recevez du texte. Aucune inscription, aucun outil à installer — votre navigateur suffit pour regarder.

Essayez, là, tout de suite

Ces trois liens s'ouvrent dans un onglet et vous montrent une vraie réponse. Cliquez, regardez, revenez :

• GET https://gamescan.fr/api/gamescan/v1/jeux?mesures=1&par_page=5 Les jeux sur lesquels on sait répondre
• GET https://gamescan.fr/api/gamescan/v1/composants/gpu?q=rtx%204070 Chercher une carte graphique
• GET https://gamescan.fr/api/gamescan/v1/meta Ce que l'API sait, et ses barèmes

À quoi ça peut vous servir ?

Lire une réponse

Voici une fiche de jeu telle qu'elle vous revient. Chaque ligne est un nom, puis sa valeur :

{
  "slug": "counter-strike-source",
  "nom": "Counter-Strike: Source",
  "sortie": "2004-11-01",
  "editeur": "Valve",
  "mesures": 6,
  "etat": "validee",
  "actif": true
}

slug

l'adresse du jeu, celle qu'on redonne à l'API pour le désigner. C'est son nom pour les programmes.

mesures

combien de relevés réels existent pour ce jeu. À zéro, GameScan ne saura rien en dire — et le dira.

etat

où en est la fiche : analysée, à vérifier, validée. Une fiche non validée peut encore bouger.

Les paliers et le ray tracing

GET /jeux/{slug} rend aussi les paliers de configuration : minimum, recommandé, ultra, puis — quand l'éditeur les publie — RT minimum, RT recommandé, RT ultra et path tracing. Voici un palier de path tracing, tel qu'il revient :

{
    "slug": "cyberpunk-2077",
    "nom": "Cyberpunk 2077",
    "ray_tracing": {
        "propose": true,
        "materiel_requis": false,
        "niveaux": [
            "rt_rec",
            "path"
        ]
    },
    "paliers": [
        {
            "cle": "path",
            "nom": "Path tracing",
            "ram": "24 Go",
            "vram": "16 Go",
            "aide": "4K · détails ultra · 60 images visées · path tracing.",
            "cartes": [
                {
                    "nom": "GeForce RTX 4080",
                    "indice": 6070,
                    "portable": false
                }
            ],
            "processeurs": [
                {
                    "nom": "Core i9-12900",
                    "indice": 5400
                }
            ],
            "ray_tracing": "path",
            "ray_tracing_label": "Path tracing",
            "definition": "3840 × 2160",
            "detail": "Ultra",
            "images_visees": 60,
            "mise_a_l_echelle": null,
            "mise_a_l_echelle_imposee": false,
            "generation_images": true,
            "generation_images_imposee": false,
            "stockage": "70 Go",
            "stockage_type": "SSD NVMe",
            "systeme": "Windows 10 64 bits",
            "note": "Préréglage Ray Tracing Overdrive (path tracing). Mesuré par l'éditeur avec la génération d'images DLSS activée. Conseillé : RTX 40 (4070 Ti et plus)."
        }
    ]
}

ray_tracing (racine)

le résumé. propose vaut true si le jeu décrit du ray tracing, false s'il n'en a pas (jeu d'avant 2018, ou fiche renseignée sans palier RT), et null quand on ne sait pas — ce n'est pas un « non ». materiel_requis : le jeu refuse de démarrer sans carte compatible. niveaux : les clefs des paliers concernés.

cle

min, rec, ultra, rt_min, rt_rec, rt_ultra, path. Seuls les paliers que l'éditeur publie sont présents.

ray_tracing (dans un palier)

non, moyen (partiel), ultra (complet) ou path (path tracing).

definition, detail, images_visees

les conditions du palier : définition, préréglage graphique, images par seconde visées.

mise_a_l_echelle, generation_images

DLSS / FSR / XeSS et génération d'images, avec …_imposee quand l'éditeur les impose.

cartes, processeurs

les pièces citées, avec leur indice (voir /composants pour son origine).

note

la précision de l'éditeur, et sa source.

Le mot le plus important : indecis

Quand aucune mesure ne permet de descendre jusqu'à la machine décrite, l'API ne fabrique pas un chiffre. Elle répond ceci :

{
  "jeu": { "slug": "un-jeu", "nom": "Un jeu" },
  "indecis": true,
  "pourquoi": "aucune mesure ne permet de descendre jusqu'à cette machine",
  "note": null,
  "confiance": null
}

Trois choses à ne pas faire

Commencer

La racine est https://gamescan.fr/api/gamescan/v1. Tout est en GET sauf deux adresses, rien ne demande d'inscription, et toutes les origines sont acceptées (Access-Control-Allow-Origin: *), contrôle préalable OPTIONS compris.

# Rien à installer : votre navigateur suffit aussi.
curl -s https://gamescan.fr/api/gamescan/v1/jeux?mesures=1&par_page=3

La forme des réponses

Elle est toujours la même, succès comme échec : un client qui doit deviner la forme d'après le statut HTTP écrit deux analyseurs, et le second est toujours le moins testé.

{
  "ok": true,
  "version": "v1",
  "data": … ,
  "meta": { "genere_le": "…" }
}

{
  "ok": false,
  "version": "v1",
  "error": {
    "code": "requete_invalide",
    "message": "…",
    "details": { … },
    "doc": "…"
  }
}

Branchez-vous sur error.code, jamais sur le message. Le texte peut être réécrit, traduit ou précisé ; le code, lui, est le contrat.

• requete_invalideHTTP 400
• cle_invalideHTTP 401
• cle_bannieHTTP 403
• introuvableHTTP 404
• methode_refuseeHTTP 405
• cadence_depasseeHTTP 429
• panneHTTP 500

Quatre conventions

Elles valent pour toutes les adresses. Les connaître dispense de lire chaque réponse dans le détail.

null

veut dire « pas mesuré », et jamais 0. Une machine sans bilan rend "note": null, pas "note": 0 — n'affichez rien dans ce cas, plutôt qu'un zéro que personne n'a calculé.

_mo

les mémoires sortent toujours en mégaoctets (ram_mo, vram_mo) : arrondir au gigaoctet ferait de 16 304 Mo un « 16 Go » qui ne revient jamais. En entrée, ram_go et ram_mo sont acceptés tous les deux.

Filtre inconnu

une valeur hors liste est refusée (400), jamais ignorée. ?type=portables au pluriel rendrait sinon la liste entière, et vous croiriez lire des portables.

Les réserves

estimee, certitude et processeur_absent voyagent avec la note. Republier une note sans elles, c'est présenter une supposition comme une mesure.

Les adresses

• GET https://gamescan.fr/api/gamescan/v1/openapi.json

  La description de cette API au format OpenAPI 3.1 — de quoi engendrer un client dans à peu près n'importe quel langage sans lire une ligne de documentation.

• GET https://gamescan.fr/api/gamescan/v1/meta

  Ce que l'API sait : décomptes, barèmes des paliers, familles d'écran, états de fiche, et votre cadence restante. À lire en premier — un client qui recopie nos seuils finit par afficher « fluide » là où nous affichons « limité ».

• GET https://gamescan.fr/api/gamescan/v1/jeux

  Le catalogue des jeux.

  q

  Cherche dans le nom et l'adresse.

  mesures

  À 1, ne rend que les jeux sur lesquels une mesure existe.

  modifie_depuis

  Date ISO-8601 : ne rend que ce qui a bougé depuis, fiches retirées comprises (« actif »: false). Pour tenir une copie à jour sans tout retélécharger.

  page

  À partir de 1.

  par_page

  1 à 100, 25 par défaut.

• GET https://gamescan.fr/api/gamescan/v1/jeux/{slug}

  Un jeu : ses paliers (minimum, recommandé, ultra, et les paliers de ray tracing — RT minimum / recommandé / ultra, path tracing — quand l'éditeur les publie, avec définition, détail, mise à l'échelle et génération d'images), un résumé « ray_tracing », la provenance de ses exigences, et CHAQUE mesure avec sa source, sa date et sa confiance.

• GET https://gamescan.fr/api/gamescan/v1/composants/{genre}

  Les cartes graphiques (genre « gpu ») ou les processeurs (« cpu »).

  q

  Cherche dans le nom.

  modifie_depuis

  Date ISO-8601 : ne rend que ce qui a bougé depuis. Même usage que pour les jeux.

  page

  À partir de 1.

  par_page

  1 à 100.

• GET https://gamescan.fr/api/gamescan/v1/composants/{genre}/{slug}

  Une pièce : ses indices AVEC LEUR ORIGINE, ses caractéristiques, les mesures qui la citent, et ce qu'on ne sait pas d'elle.

• GET https://gamescan.fr/api/gamescan/v1/analyses

  Les machines analysées. UNE LIGNE PAR MACHINE, pas par relance : la signature dédoublonne, et « vues » dit combien de fois la configuration a été analysée.

  type

  « portable » ou « fixe ».

  tri

  « note » pour les meilleures d'abord.

  page

  À partir de 1.

  par_page

  1 à 100.

• GET https://gamescan.fr/api/gamescan/v1/classement

  Le palmarès. ⚠️ Il n'a pas le même périmètre que /analyses : une machine n'y entre que si au moins un jeu a pu être chiffré pour elle et si sa configuration est reconnue assez précisément. Le bloc meta dit combien sont écartées.

  type

  « portable » ou « fixe ».

  page

  À partir de 1.

• GET https://gamescan.fr/api/gamescan/v1/analyses/{jeton}

  Une analyse publique, par le code à 16 caractères qui figure dans son adresse. Aucune identité n'en sort : une analyse est une configuration, jamais quelqu'un.

• POST https://gamescan.fr/api/gamescan/v1/verdict

  LE CŒUR : vous décrivez une machine, l'API rend ce que chaque jeu y donne, avec sa fourchette d'incertitude — ou « indecis » quand aucune mesure ne permet de descendre jusqu'à cette machine.

• POST https://gamescan.fr/api/gamescan/v1/scans

  Dépose un relevé de machine et rend son code public. C'est la voie qu'emprunte le logiciel GameScan. Aucune clé n'est exigée.

Demander un verdict

Décrivez une machine, l'API rend ce que chaque jeu y donne. Seule la carte graphique est obligatoire — c'est d'elle que descend le calcul. Sans processeur, aucun plafond n'est posé et la réponse est optimiste par construction : le champ meta.machine.processeur_absent le dit.

POST https://gamescan.fr/api/gamescan/v1/verdict
Content-Type: application/json

{
  "gpu": "geforce-rtx-4070",
  "cpu": "ryzen-7-7700",
  "ram_mo": 32768,
  "definition": "2560x1440",
  "hz": 144,
  "chassis": "fixe",
  "jeux": ["counter-strike-source"]
}

Les champs de la machine peuvent aussi être posés à la racine du corps, sans l'enveloppe machine : les deux écritures sont acceptées, pour que lire deux pages de cette documentation ne coûte pas une erreur. jeux, lui, reste à la racine.

Une ligne de la réponse :

{
  "jeu": { "slug": "counter-strike-source", "nom": "Counter-Strike: Source" },
  "indecis": false,
  "note": 90,
  "confiance": 53,
  "fiabilite": {
    "cle": "moyenne",
    "nuance": "Probablement",
    "phrase": "Prenez ce chiffre comme une estimation : il situe votre machine, il ne la mesure pas.",
    "raisons": ["l'indice de puissance de votre carte est estimé, pas relevé"]
  },
  "provenance": "estimation",
  "reglages": [
    {
      "definition_px": "2560 × 1440",
      "detail": "Ultra",
      "images": 240,
      "images_vues": 144,
      "palier_label": "Excellent",
      "bride_par": "cpu"
    }
  ]
}

Les adresses des pièces se trouvent avec https://gamescan.fr/api/gamescan/v1/composants/gpu?q=…. Une pièce inconnue est refusée en le disant — et l'erreur porte un details.chercher déjà prêt à appeler. Si aucune mesure ne permet de descendre jusqu'à cette machine, la ligne du jeu porte "indecis": true et un pourquoi : n'affichez rien dans ce cas, c'est le sens de la réponse.

Tenir une copie à jour

modifie_depuis sur /jeux et /composants/{genre} ne rend que ce qui a bougé. Recopier le catalogue entier à chaque passage coûte des centaines de fiches pour en découvrir une :

# 1. La première fois, on prend tout.
curl -s 'https://gamescan.fr/api/gamescan/v1/jeux?par_page=100&page=1'

# 2. Ensuite, on ne redemande QUE ce qui a bougé.
#    « modifie_depuis » = le « jusqu_a » de l'appel précédent.
curl -s 'https://gamescan.fr/api/gamescan/v1/jeux?modifie_depuis=2026-09-24T18:41:24+00:00'

{
  "data": [
    { "slug": "cyberpunk-2077", "actif": false, "modifie_le": "2026-09-24T20:41:25+02:00" }
  ],
  "meta": {
    "total": 1,
    "synchronisation": {
      "jusqu_a": "2026-09-24T18:43:04+00:00",
      "total_collection": 167
    }
  }
}

actif

à false, la fiche a été retirée du site : effacez-la de votre copie. Sans ce champ, elle y resterait à vie.

jusqu_a

à renvoyer tel quel au prochain appel. La borne est inclusive : quelques fiches déjà connues repasseront, c'est voulu — les manquer ne se rattrape pas.

total_collection

le nombre de fiches actives aujourd'hui. Si vous en détenez davantage, une suppression définitive vous a échappé — elle ne repasse dans aucun flux : refaites une copie complète.

Engendrer un client

https://gamescan.fr/api/gamescan/v1/openapi.json décrit cette API au format OpenAPI 3.1 : adresses, méthodes, paramètres, codes d'erreur, enveloppe et clé facultative. De quoi engendrer un client dans à peu près n'importe quel langage sans lire cette page.

Le document est engendré depuis la même carte que /meta et que la liste ci-dessus : il ne peut pas annoncer une adresse que l'API ignore. En revanche il ne décrit pas le contenu de data adresse par adresse — le faire à la main aurait créé une seconde description, qui aurait fini par diverger. Cette partie-là se lit ici.

La cadence

600 appels par heure sans clé, comptés par adresse d'appelant. Chaque réponse porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; au-delà, l'API répond 429 avec Retry-After. Les listes rendent au plus 100 éléments par page.

Les lectures repartent avec Cache-Control: public, max-age=60 : laissez votre client ou votre relais les garder une minute plutôt que de redemander la même liste à chaque visiteur — cela ne consomme pas votre cadence et vos pages s'affichent plus vite. Les écritures et les erreurs ne sont jamais mises en cache.

GET https://gamescan.fr/api/gamescan/v1/jeux
X-GameScan-Key: gns_votre_cle_ici