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.
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