Accès à un document via son id

Toutes les URL suivantes sont accédées via la méthode HTTP GET.

Pour récupérer la liste des champs et formats (métadonnées, fulltext, annexes, covers, enrichments) disponibles pour un document, il est possible d'effectuer une requête sous la forme :

Syntaxe
URI https://api.istex.fr/document/{id}
Paramètres - {id} : l'identifiant ISTEX du document auquel correspond la notice.
Code de retour - 200 si OK,
- 404 si la notice n'est pas trouvée
Exemple https://api.istex.fr/document/55420CDEEA0F6538E215A511C72E2E5E57570138

Niveau d'arborescence

Les niveaux d'arborescence d'un champ sont ici représentés par des . (points). Par exemple, pour avoir le numéro de la première page présente dans le host, on utilisera le champ host.pages.first.

Explication sur la granularité

La granularité désigne le niveau hiérarchique des documents pris en compte dans l’API. En effet, pour les ressources de type journal, l’information peut porter tantôt sur la revue, tantôt sur l’article, parfois même sur la série.

Exemple explicatif de la granularité

Au niveau de l’API, un enregistrement sera toujours pris au niveau de l’article (cadre vert). Un bloc spécial, host, permet d’accéder aux informations de niveau revue (cadre rouge). Ce bloc rouge sera donc identique pour tous les articles d’une même revue.

Lorsque l’objet documentaire est de type monographie ou livre électronique, le niveau de granularité de l’API est le chapitre (cadre vert). Le cadre rouge contiendra toutes les informations correspondant au livre.

Explication sur les champs de type .raw

Les champs de type string possèdent tous un sous-champ raw. Ce dernier permet d'interroger le champ père, de manière non segmentée.

Par exemple, le champ corpusName possède un champ corpusName.raw. La requête https://api.istex.fr/document/?q=corpusName:brill-journals&facet=corpusName va renvoyer les résultats contenant soit le terme "brill", soit "journals". On voit donc dans le résultat de la facette :

  aggregations: {
    corpusName: {
      docCountErrorUpperBound: 0,
      sumOtherDocCount: 0,
      buckets: [
        {
          key: "rsc-journals",
          docCount: 294458
        },
        {
          key: "degruyter-journals",
          docCount: 238361
        },
        {
          key: "brill-journals",
          docCount: 127470
        },
        {
          key: "brill-hacco",
          docCount: 11182
        }
      ],
      keyCount: 4
    }
  }

La requête https://api.istex.fr/document/?q=corpusName.raw:brill-journals&facet=corpusName quant à elle renverra les résultats contenant exactement le terme "brill-journals" :

  aggregations: {
    corpusName: {
      docCountErrorUpperBound: 0,
      sumOtherDocCount: 0,
      buckets: [
        {
          key: "brill-journals",
          docCount: 127470
        }
      ],
      keyCount: 1
    }
  }

Ce champ a été créé pour les facettes, mais peut être utilisé par l'utilisateur. On lui préférera cependant la version classique (segmentée), qui permet une recherche plus avancée. Pour obtenir le même résultat précédent, il suffit alors de délimiter le mot avec des guillemets : https://api.istex.fr/document/?q=corpusName:"brill-journals"&facet=corpusName

Explication sur les indicateurs de qualité

Les indicateurs de qualité sont rassemblés sous le champ qualityIndicators.

Ces derniers contiennent des informations supplémentaires sur le contenu du fulltext et des métadonnées, calculé en amont de la chaîne. En effet, on y retrouvera :

Champs Type Détails
qualityIndicators {} Objet contenant l'ensemble des informations supplémentaires
qualityIndicators.abstractCharCount integer Nombre de caractères dans le résumé
qualityIndicators.abstractWordCount integer Nombre de mots dans le résumé (basé sur le nombre d'espace)
qualityIndicators.keywordCount integer Nombre de mots clés présents
qualityIndicators.pdfCharCount integer Nombre de caractères dans le PDF
qualityIndicators.pdfPageCount integer Nombre de pages du PDF
qualityIndicators.pdfPageSize string Taille des pages du PDF (format : "X x Y pts")
qualityIndicators.pdfVersion string Numéro de version du PDF
qualityIndicators.pdfWordCount integer Nombre de mots dans le PDF (basé sur le nombre d'espace)
qualityIndicators.refBibsNative boolean Indique si les références bibliographiques sont fournis par l'éditeur
qualityIndicators.score double Score de qualité, calculé selon les critères précédents (voir ici pour plus de détails)

Ces informations sont extraites des métadonnées des fichiers, ou directement calculées par nos outils. Si un champ n'est pas renseigné pour un objet documentaire, cela signifie que cette information n'est pas disponible pour le moment.

Explication sur les références bibliographiques

Les références bibliographiques sont rassemblées sous le champ refBibs.

Ces dernières sont soit fournies par l'éditeur, soit extraites à l'aide de l’outil d'analyse GROBID à partir du PDF. On y retrouvera :

Champs Type Détails
refBibs [{}] Tableau d'objets, chaque objet correspondant à une référence bibliographique
refBibs.author [{}] Tableau d'objets, chaque objet correspondant à un auteur référencé
rebBibs.author.name string Nom d'un auteur référencé
refBibs.host {} Objet contenant les informations liées à la revue ou le livre (voir le chapitre sur la granularité)
refBibs.host.author [{}] Tableau d'objets, chaque objet correspondant à un auteur de la revue référencée
refBibs.host.author.name string Nom d'un auteur de la revue référencée
refBibs.host.issue integer Numéro de la revue référencée
refBibs.host.pages {} Objet contenant les données sur les pages, liés à la revue
refBibs.host.pages.first integer Première page de la revue référencée
refBibs.host.pages.last integer Dernière page de la revue référencée
refBibs.host.publicationDate date Date de publication de la revue référencée
refBibs.host.title string Titre de la revue référencée
refBibs.host.volume integer Numéro de volume de la revue référencée
refBibs.publicationDate date Date de publication référencée
refBibs.title string Titre référencé

Si un champ n'est pas renseigné pour un objet documentaire, cela signifie que cette information n'est pas disponible pour le moment.

Autres champs uniquement liés à l'article

D'autres champs sont également présents uniquement au niveau de l'article :

Champs Type Détails
abstract string Résumé du document
articleId string -------------
categories {} Objet contenant les informations liées aux catégories
categories.inist [string] Tableau contenant toutes les catégories déterminées par méthode bayésienne du document
categories.scienceMetrix [string] Tableau contenant toutes les catégories Science-Metrix du document
categories.wos [string] Tableau contenant toutes les catégories Web Of Science du document
chapterId string -------------
corpusName string Nom du corpus auquel appartient le document (ex : "elsevier")
enrichments.type [string] Indique la nature des enrichissements disponibles (ex : "multicat","refBibs")
keywords {} Objet contenant les informations liées aux mots-clés
keywords.teeft [string] Tableau contenant tous les termes anglais extraits par étiquetage morpho-syntaxique
namedEntities {} Objet contenant les informations liées aux entités nommées
namedEntities.unitex [string] Tableau contenant toutes les entités nommées détectées par Unitex-CasSys
originalGenre string Genre du document fourni par l'éditeur
pmid string Identifiant PubMed du document

Si un champ n'est pas renseigné pour un objet documentaire, cela signifie que cette information n'est pas disponible pour le moment.

Champs uniquement liés au niveau revue

Certains champs sont également présents uniquement au niveau de la revue, c'est-à-dire précédés de host (voir le chapitre sur la granularité) :

Champs Type Détails
host.bookId string -------------
host.conference [{}] Tableau d'objets, chaque objet correspondant à une conférence
host.conference.name string Nom de la conférence
host.eisbn string International Standard Book Number électronique
host.eissn string International Standard Serial Number électronique
host.isbn string International Standard Book Number papier
host.issn string International Standard Serial Number papier
host.issue integer Numéro de la revue
host.journalId string -------------
host.pages {} Objet contenant les données sur les pages de l'article dans la revue
host.pages.first integer Première page de l'article dans la revue
host.pages.last integer Dernière page de l'article dans la revue
host.pages.total integer Nombre de pages de l'article dans la revue
host.publisherId string -------------
host.volume integer Volume de la revue

Si un champ n'est pas renseigné pour un objet documentaire, cela signifie que cette information n'est pas disponible pour le moment.

Champs dépendant de la granularité

La liste suivante concerne les champs disponibles à la fois au niveau de l'article et au niveau de la revue ou livre (voir le chapitre sur la granularité). Pour changer entre ces deux niveaux de granularité, il suffit d'ajouter le champ host pour accéder aux données niveau revue, et de ne rien ajouter pour les données niveau article :

Champs Type Détails
author [{}] Tableau d'objets, chaque objet correspondant à un auteur
author.affiliations [string] Tableau des affiliations de l'auteur, liées à l'article ou la revue
author.name string Nom de l'auteur, lié à l'article ou la revue
copyrightDate date Date de copyright de l'article ou de la revue
doi string Digital Object Identifier de l'article ou de la revue
editor [{}] Tableau d'objets, chaque objet correspondant à un rédacteur
editor.affiliations [string] Tableau des affiliations du rédacteur, liées à l'article ou la revue
editor.name string Nom du rédacteur, lié à l'article ou la revue
genre string Type d'article ou de revue
language string Langue de l'article ou de la revue
pii string Personally Identifiable Information de l'article ou de la revue
publicationDate date Date de publication de l'article ou de la revue
subject [{}] Tableau d'objets, chaque objet correspondant à un thème
subject.language string Langue du thème de l'article ou de la revue
subject.value string Thème de l'article ou de la revue
title string Titre de l'article ou de la revue

Si un champ n'est pas renseigné pour un objet documentaire, cela signifie que cette information n'est pas disponible pour le moment.

Champs d'accès aux fichiers liés au document

A ces listes de champs s'ajoutent la suivante, permettant de consulter les fichiers liés au document en question. Ces champs ne sont pas interrogeables, et l'accès à ces fichiers sera détaillé dans les sections suivantes :

Champs Type Détails
annexes.extension string Extension du fichier d'annexe (ex : "jpeg")
annexes.mimetype string Mimetype du fichier du fulltext (ex : "image/jpeg")
annexes.original boolean Indique si le fichier d'annexe vient de l'éditeur
annexes.uri string Chemin d'accès au fichier d'annexe
covers.extension string Extension du fichier de cover (ex : "gif")
covers.mimetype string Mimetype du fichier du fulltext (ex : "image/gif")
covers.original boolean Indique si le fichier de cover vient de l'éditeur
covers.uri string Chemin d'accès au fichier de cover
enrichments.{type} {} Objet contenant les informations liées au type d'enrichissement {type} (ex: {type}=refBibs)
enrichments.{type}.extension string Extension du fichier d'enrichissement de type {type} (ex: "tei")
enrichments.{type}.mimetype string Mimetype du fichier d'enrichissement de type {type} (ex: "application/tei+xml")
enrichments.{type}.original boolean Indique si le fichier d'enrichissement de type {type} vient de l'éditeur
enrichments.{type}.uri string Chemin d'accès au fichier d'enrichissement de type {type}
fulltext.extension string Extension du fichier du fulltext (ex : "pdf")
fulltext.mimetype string Mimetype du fichier du fulltext (ex : "application/pdf")
fulltext.original boolean Indique si le fichier du fulltext vient de l'éditeur
fulltext.uri string Chemin d'accès au fichier du fulltext
metadata.extension string Extension du fichier de métadonnées (ex : "xml")
metadata.mimetype string Mimetype du fichier du fulltext (ex : "application/xml")
metadata.original boolean Indique si le fichier de métadonnées vient de l'éditeur
metadata.uri string Chemin d'accès au fichier de métadonnées

Liste des éditeurs disponibles

La liste des éditeurs est disponible via la requête https://api.istex.fr/corpus/

Pour consulter la liste complète des éditeurs prévus dans l'API ISTEX, ou pour plus de détails sur les corpus déjà disponibles, nous vous invitons à consulter le site Licences Nationales