MétaCan
Menu
API

La même requête, en point d’accès.

Chaque écran consomme des points d'accès publics. La page, l'API et l'export analysent les mêmes paramètres avec la même fonction : aucune surface ne peut répondre à une question différente d'une autre.

Lecture seule, JSON, CORS ouvert, sans clé. Chaque point d'accès s'appuie sur les mêmes fonctions que les pages : searchWorks() sert à la fois /works et /api/v1/works, de sorte que l'API ne peut pas répondre à une autre question que la page au-dessus d'elle.

URL de base : https://metacan.xera.ac/api/v1

MéthodePoint d’accèsDescription
GET/api/v1/cohortCompter et paginer une cohorte pour tout ensemble de filtres
GET/api/v1/works/{id}Une notice : routes, étiquettes, prédictions, provenance
GET/api/v1/facets/{facet}Valeurs d'autocomplétion : revue, sujet
POST/api/v1/permalinkCréer un permalien citable /q/ vers une requête épinglée
GET/api/v1/cohort/exportExport CSV ou JSON de la cohorte courante, plafonné
GET/api/v1/recentLa couche en direct, synchronisée chaque jour
GET/api/v1/screenedLe tri à trois modèles, avec verdicts et poids de sondage
GET/api/v1/stats/…Agrégats de la base : sommaire, années, routes, domaines, étiquettes
GET/api/v1/findingsLe fichier des constats écrit par les scripts du pilote, tel quel
GET /api/v1/cohort?route_fund=1&route_aff=0&lang=fr200
{
  "meta": {
    "total": 6784,
    "direct_labels_cover": 23,
    "predictions_cover": 6784,
    "query_hash": "23b0df378a31",
    "filters": { "route_fund": true,
                 "route_aff": false,
                 "lang": "fr" }
  },
  "results": [ … ]
}

Remarques

  • CORS est ouvert (*). C'est un jeu de données de recherche public sous CC-BY ; l'intérêt de le publier est que vous puissiez l'interroger depuis votre propre page sans serveur mandataire.
  • Cache. Les réponses portent s-maxage=3600. La base est un instantané épinglé : elle ne change pas entre les déploiements, un agrégat un peu vieux n'est donc pas un risque, alors que rebalayer 4,3 M de rangées à chaque requête en serait un.
  • Sans clé, sans limite de débit, mais c'est un seul petit serveur. Restez raisonnable, et s'il vous faut toute la base, prenez le dépôt et reconstruisez-la localement plutôt que d'en paginer quatre millions de rangées hors de cette machine.
  • Licence. Données CC BY 4.0, code MIT. Citez OpenAlex et Retraction Watch comme sources amont.
GET/api/v1/cohort

La requête du constructeur de cohortes lui-même. Même analyseur, même fonction que la page d'accueil, de sorte que l'API ne peut pas répondre à une autre question que la page au-dessus d'elle. Accepte tous les paramètres de /api/v1/works, plus les facettes ci-dessous.

Le compte est exact, et la couverture des étiquettes l'accompagne. meta.total est le vrai N (une cohorte se cite par son N), et meta.direct_labels_cover indique la couverture des étiquettes directes, tandis que meta.predictions_cover indique celle des prédictions. Un tableau labels vide signifie non étiqueté, jamais « hors de la catégorie ».
ParamètreTypeSignification
topicstringSujet principal OpenAlex exact. Les valeurs viennent de la saisie semi-automatique : /api/v1/facets/topic?q=…
venuestringNom de revue exact. Les valeurs viennent de /api/v1/facets/venue?q=…
route_aff, route_fund, route_venue, route_about1 | 0Facettes de voies à trois états : 1 exige la voie, 0 l'exclut, absent signifie « toutes ». Elles se composent (route_fund=1&route_aff=0 donne la strate financée-seulement), ce que le seul paramètre route ne peut pas exprimer.
retracted1 | 01 = rétractés seulement; 0 = exclure les rétractés; absent = tous.
abstracthas | nonehas = seulement les travaux avec résumé; none = seulement ceux sans résumé.
categorymetaresearch | metaepi_narrow | metaepi_broad | bibliometrics | sts | scholarly_communication | open_science | research_integrityFacette de catégorie. Sa source de preuve est choisie par label_source. Les étiquettes directes et les prédictions ne sont pas validées.
designrandomized_trial | nonrandomized_trial | observational | systematic_review | meta_analysis | case_report | qualitative | simulation_or_modeling | bench_or_experimental | theoretical_or_conceptual | not_applicable | design_otherFacette de devis d'étude. Sa source de preuve est choisie par label_source. Aucun devis n'est encore validé contre MEDLINE.
label_sourcedirect | predicteddirect utilise les sorties directes et clairsemées des modèles. predicted utilise les sorties de distillation sur toute la base. Aucune n'est validée par des humains.
prediction_modecandidate | consensuscandidate utilise l'union des têtes Codex et Gemma seuillées. consensus utilise leur intersection.
agreementany | allPour les étiquettes directes seulement. any signifie qu'un modèle suffit; all signifie que chaque modèle ayant étiqueté le travail concorde sur la valeur filtrée.
labeled1 | 0Pour les étiquettes directes seulement. 1 exige une rangée d'étiquette directe; 0 exige son absence.
# Travaux de métarecherche étiquetés directement, avec couverture exacte :
curl -sS "https://metacan.xera.ac/api/v1/cohort?label_source=direct&category=metaresearch" \
  | jq '{total: .meta.total, direct: .meta.direct_labels_cover}'

# Prédictions de consensus pour la métarecherche :
curl -sS "https://metacan.xera.ac/api/v1/cohort?label_source=predicted&prediction_mode=consensus&category=metaresearch" \
  | jq '{total: .meta.total, predicted: .meta.predictions_cover, first: .results[0].prediction}'
GET/api/v1/cohort/export

La cohorte entière en un fichier, diffusé depuis la base de données : toutes les colonnes des travaux, les étiquettes directes, les données complètes de prédiction, les anciens scores provisoires et les champs d'état par rangée.

Plafonné à 100 000 rangées. La troncature n'est jamais silencieuse : elle est déclarée dans meta.truncated (JSON), dans une ligne de commentaire finale (CSV) et dans l'en-tête X-Export-Truncated. Au-delà du plafond, resserrez la cohorte ou reconstruisez la base depuis le dépôt.
ParamètreTypeSignification
formatcsv | jsoncsv (défaut) ou json. Tout le reste suit le même vocabulaire de filtres que /api/v1/cohort.
# Une cohorte étiquetée en CSV :
curl -sSL "https://metacan.xera.ac/api/v1/cohort/export?category=metaresearch&format=csv" -o cohort.csv

# En JSON, métadonnées d'abord :
curl -sS "https://metacan.xera.ac/api/v1/cohort/export?design=systematic_review&year_from=2020&format=json" | jq '.meta'
POST/api/v1/permalink

Créer le permalien citable /q/<hash> d'un état de filtres. Idempotent : le hachage est une fonction des filtres canoniques, la même cohorte reçoit donc toujours la même URL, qui que soit le demandeur et quel que soit le moment.

curl -sS -X POST "https://metacan.xera.ac/api/v1/permalink?label_source=predicted&prediction_mode=consensus&category=metaresearch" \
  | jq '{url, total, direct_labels_cover, predictions_cover}'
GET/api/v1/facets/{venue,topic}

Saisie semi-automatique sur les ~85 000 revues distinctes et ~4 500 sujets distincts, avec les comptes sur toute la base. Deux caractères au minimum.

curl -sS "https://metacan.xera.ac/api/v1/facets/venue?q=canadian+journal" | jq '.results[:3]'
curl -sS "https://metacan.xera.ac/api/v1/facets/topic?q=peer+review" | jq '.results[:3]'
GET/api/v1/facets/author

Saisie semi-automatique sur les personnes ayant une signature affiliée au Canada, classées par production canadienne. Retourne l’identifiant OpenAlex désambiguïsé (A...) à côté de chaque nom ; c’est cet identifiant que consomment ?author_id= et le point d’accès du réseau. Deux caractères au minimum.

curl -sS "https://metacan.xera.ac/api/v1/facets/author?q=tricco" | jq '.results[:3]'
GET/api/v1/network

Le réseau de collaboration intra-Canada. Sans paramètre : le graphe d’ensemble des liens les plus forts. Avec author_id : le voisinage de cette personne. Le bloc meta énonce les règles de construction (nœuds, liens, pondération fractionnaire, garde de densité) dans chaque réponse, car un graphe dont les règles ne sont pas dans la réponse n’est pas citable.

ParamètreTypeSignification
author_idstringIdentifiant OpenAlex de l’auteur (A...). Omettre pour le graphe d’ensemble.
curl -sS "https://metacan.xera.ac/api/v1/network?author_id=A5044517411" | jq '.meta, .graph.nodes[:3]'
GET/api/v1/stats/labels

Le panorama des étiquettes : couverture, catégories, devis d'étude, années et langues sur le sous-ensemble étiqueté par machine. La même fonction que rend la page Panorama, de sorte que les deux ne peuvent pas diverger.

curl -sS https://metacan.xera.ac/api/v1/stats/labels | jq '{coverage, top: .by_category[:3]}'
GET/api/v1/stats/summary

La base en un seul objet : le total des travaux, les comptes sans affiliation et sans résumé, les marginales des quatre voies, et l'histogramme de consensus du tri.

curl -sS https://metacan.xera.ac/api/v1/stats/summary | jq
GET/api/v1/works

Parcourir et chercher toute la base. Plein texte sur les titres, tous les filtres de la page de consultation, paginé.

Le compte est plafonné à 10 000. Compter exactement 4,3 M de rangées coûte des secondes et personne ne lit le nombre ; total_is_capped: true signifie donc « au moins 10 000 », et non « exactement 10 000 ». Paginez s'il vous en faut davantage.
ParamètreTypeSignification
qstringRecherche plein texte sur les titres (tsvector Postgres ; les termes sont liés par ET).
authorstringRecherche par nom d’auteur sur la couche des auteurs (mêmes sémantiques websearch que q). Un nom est un filet large : il peut correspondre à plusieurs identités OpenAlex ; author_id est la forme précise.
author_idstringIdentifiant OpenAlex exact de l’auteur (A...), l’identité désambiguïsée. Le filtre citable.
year_from, year_tointBornes inclusives sur l’année de publication.
cited_minintNombre minimal de citations (cited_by >= N).
langstringCode de langue, p. ex. en, fr.
typestringType de travail, p. ex. article, preprint, dissertation.
fieldstringDomaine principal OpenAlex, p. ex. 'Medicine'.
routeaff | fund | venue | about | no_affProvenance par voie : pourquoi le travail est dans la base. no_aff renvoie les travaux SANS affiliation canadienne, ceux qu'une base fondée sur la seule affiliation ne voit jamais.
retracted1Seulement les travaux qu'OpenAlex signale comme rétractés.
no_abstract1Seulement les travaux sans résumé. Le tri y repère moitié moins de métarecherche.
n_in0..3Consensus du tri : combien des trois modèles ont qualifié le travail de métarecherche.
sortcited | year_desc | year_ascPar défaut : cited.
page, per_pageintper_page : 100 au maximum, 25 par défaut.
# Les travaux qu'une base fondée sur la seule affiliation n'aurait jamais vus,
# les plus cités d'abord :
curl -sS "https://metacan.xera.ac/api/v1/works?route=no_aff&sort=cited&per_page=5" | jq '.results[] | {id, title, cited_by, routes}'

# Travaux en français, sans résumé, parus depuis 2015 :
curl -sS "https://metacan.xera.ac/api/v1/works?lang=fr&no_abstract=1&year_from=2015&per_page=5" | jq

# Recherche plein texte :
curl -sS "https://metacan.xera.ac/api/v1/works?q=reproducibility+crisis&per_page=3" | jq '.results[].title'
GET/api/v1/works/{id}

Un travail avec tous les champs de la base, la provenance des voies, l'état Retraction Watch, les étiquettes directes de modèles et la prédiction sur toute la base avec les scores des modèles enseignants et les champs d'incertitude.

ParamètreTypeSignification
abstract1Récupérer le résumé en direct depuis OpenAlex et le désinverser. Désactivé par défaut : les résumés ne sont pas dans cette base de données, en demander un coûte donc un aller-retour vers l'amont.
# Un travail, avec sa provenance :
curl -sS https://metacan.xera.ac/api/v1/works/W2342586781 | jq '{id, title, routes}'

# Avec le résumé récupéré en direct depuis OpenAlex :
curl -sS "https://metacan.xera.ac/api/v1/works/W2342586781?abstract=1" | jq '.abstract'
GET/api/v1/screened

Les 5 600 travaux triés, avec les niveaux, genres, confiances et motifs des trois modèles, plus le poids de sondage.

L'échantillon est stratifié. Chaque notice porte un weight (l'inverse de la probabilité de sélection). Tout taux calculé sur ces rangées sans appliquer le poids est faux.
ParamètreTypeSignification
contested_only1LE DOSSIER DES DÉSACCORDS : chaque travail qu'au moins un modèle a qualifié de métarecherche. Ce sous-ensemble, et non le taux de base, est le livrable du projet.
n_in0..3Compte de consensus exact.
stratumstringp. ex. aff_core, about_only, french, venue_new, fund_new.
page, per_pageintper_page : 100 au maximum.
# Le dossier des désaccords : les travaux qui marquent la frontière du domaine.
curl -sS "https://metacan.xera.ac/api/v1/screened?contested_only=1" | jq '.meta.summary'

# Les travaux qu'un SEUL modèle a qualifiés de métarecherche :
curl -sS "https://metacan.xera.ac/api/v1/screened?n_in=1" \
  | jq '.results[] | {title, opus: .opus.tier, gpt: .gpt.tier, grok: .grok.tier}'
GET/api/v1/stats/by-route

Les quatre voies : marginales, et combinaisons exactes de voies.

Les voies se recoupent (un travail peut être admis par plusieurs) : marginals totalise donc plus que la base. combinations compte chaque travail une seule fois et totalise le total exact.
curl -sS https://metacan.xera.ac/api/v1/stats/by-route | jq '{no_aff: .meta.no_aff, marginals, combinations: .combinations[:5]}'
GET/api/v1/stats/by-year

Les travaux par année, avec en regard les comptes sans affiliation et sans résumé, parce que les deux écarts évoluent dans le temps.

curl -sS https://metacan.xera.ac/api/v1/stats/by-year | jq '.results[-5:]'
GET/api/v1/stats/by-field

La répartition par domaine, plus les langues, l'écart des résumés par type, les principales revues, les principaux organismes subventionnaires et le dossier de rétractation à quatre états : tout ce que dessine la page Analytique, en un seul appel.

curl -sS https://metacan.xera.ac/api/v1/stats/by-field | jq '.retraction_states'
GET/api/v1/findings

Les 32 constats, servis tels quels depuis le fichier qu'écrivent les scripts du pilote. Chaque nombre du pilote cité sur ce site vient d'ici.

curl -sS https://metacan.xera.ac/api/v1/findings | jq '.findings.three_model_screen.headline'
GET/api/v1/predictions

Le sommaire des prédictions sur toute la base et le rapport d'évaluation du modèle, servis directement depuis les artefacts produits par le pilote. Ils comprennent les empreintes de la source et du modèle, la version, les comptes par catégorie, les règles, les résultats de validation croisée et les limites. Chaque score mesure la fidélité aux modèles enseignants, non l'exactitude humaine, et chaque prédiction est produite par machine et non validée.

curl -sS https://metacan.xera.ac/api/v1/predictions | jq '{status: .predictions.prediction_status, n: .predictions.n_predictions, evidence: .meta.evidence_level, limitations: .predictions.limitations}'