Syntaxe des requêtes

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

La recherche s'effectue sous la forme :

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q={query} | | Paramètres | - q= : la lettre clé permettant d'indiquer que ce qui suit est la requête,
- {query} : la chaîne de recherche. Celle-ci correspond à une requête du type "Google" ou "Bing".
Plus de précisions sur cette page de la documentation de Lucene. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

Formatage des résultats renvoyés :

{
    total : nombre de résultats,
    hits : [
        {
            id : id du document,
            title : titre du document,
            abstract : résumé du document,
            metadata : [
                {
                    type : type MIME du document,
                    uri : URI d'accès au document,
                    original : document d'origine éditeur ou généré par nos soins
                }
                ,
                ...
                (suite des formats de métadonnées disponibles)
            ],
            fulltext : [
                {
                    type : type MIME du document,
                    uri : URI d'accès au document,
                    original : document d'origine éditeur ou généré par nos soins
                }
                ,
                ...
                (suite des formats de fulltext disponibles)
            ]
        }
        ,
        (suite des résultats)
        ...
    ]
}

Les requêtes prises en charge sont celles suivant la syntaxe de la bibliothèque de recherche Lucene.

De manière générale, une requête est une suite de termes recherchés.

De base, les termes sont recherchés dans tous les champs indexés (titre, auteur, résumé, fulltext...).

| Exemples | |------------ | ------------- | | Recherche des documents contenant le mot "Controllability" dans tous les champs indexés | https://api.istex.fr/document/?q=Controllability | Recherche des documents contenant le mot "test" dans tous les champs indexés | https://api.istex.fr/document/?q=test

Les termes cherchés sont reliés par des opérateurs booléens, l'opérateur OR étant celui par défaut. Les opérateurs supportés sont OR, AND, NOT, ainsi que les opérateurs d'inclusion/exclusion + et -.

| Exemples | | -------- | ------- | | Recherche des documents contenant le terme "api" ou "study" dans un de leurs champs indexés | https://api.istex.fr/document/?q=api OR study
https://api.istex.fr/document/?q=api study | | Recherche des documents contenant le terme "test" et "study" dans un de leurs champs indexés | https://api.istex.fr/document/?q=test AND study | Recherche des documents contenant le terme "test" mais pas "study" dans un de leurs champs indexés | https://api.istex.fr/document/?q=test NOT study
https://api.istex.fr/document/?q=api -study

L'utilisation de jokers * et ? est possible, permettant de remplacer un certain nombre de caractères.

| Exemples | | -------- | ------- | | Recherche des documents contenant un terme commençant par "te", ayant 0, 1 ou plusieurs caractères supplémentaires et finissant par un "t" dans un de leurs champs indexés (ex: "test", "tegument") | https://api.istex.fr/document/?q=te*t | | Recherche des documents contenant un terme commençant par "te", ayant 1 caractère supplémentaire et finissant par un "t" dans un de leurs champs indexés (ex: "tet", "test") | https://api.istex.fr/document/?q=te?t

L'utilisation d'expressions régulières est également disponible, à l'aide des délimiteurs //. Elles se basent sur la classe java RegExp.

| Exemples | | -------- | ------- | | Recherche des documents contenant le terme "ham", "jam" ou "hamster" dans un de leurs champs indexés | https://api.istex.fr/document/?q=/[hj]am(ster)?/ | | Recherche des documents contenant un terme avec 25 caractères parmi les lettres A, C, G et T dans un de leurs champs indexés | https://api.istex.fr/document/?q=/[CGAT]{25}/

Il est également possible d'effectuer des recherches de type "fuzzy", basées sur la distance de Damerau-Levenshtein. Pour cela, il suffit de rajouter le symbole ~ (tilde) à la fin du terme recherché.

| Exemples | | -------- | ------- | | Recherche des documents contenant un terme proche du mot "ham" dans un de leurs champs indexés | https://api.istex.fr/document/?q=ham~ |

La recherche de proximité permet, quant à elle, de trouver une suite de mots, distant d'une valeur définie. Il suffit d'utiliser les "" (guillemets) pour rassembler les mots, puis d'ajouter un ~ (tilde) accompagné de la distance (nombre entier).

| Exemples | | -------- | ------- | | Recherche des documents contenant les termes "ham" et "jam" distants d'une longueur de 10 mots dans un de leurs champs indexés | https://api.istex.fr/document/?q="ham jam"~10 |

L'API permet également de privilégier des termes lors de la recherche, avec l'aide du symbole ^ (puissance) suivant le ou les termes à amplifier, et accompagné d'un nombre facteur. Plus ce nombre est élevé, plus le terme sera privilégié par rapport aux autres. Ce nombre est obligatoirement un nombre positif, mais peut être inférieur à 1 (par exemple, 0.5).

| Exemples | | -------- | ------- | | Recherche des documents contenant les termes "ham" et "jam", avec une importance deux fois plus grande pour "ham" | https://api.istex.fr/document/?q=ham^2 jam
https://api.istex.fr/document/?q=ham^4 jam^2
https://api.istex.fr/document/?q=ham jam^0.5 | | Recherche des documents contenant les termes "ham jam" et "old", avec une importance deux fois plus grande pour "ham jam" | https://api.istex.fr/document/?q="ham jam"^2 old |

Il est possible d'interroger un champ particulier, à partir du moment où ce dernier est bien indexé. En effet, tous les objets documentaires sont homogénéisés, c'est-à-dire qu'un même type d'information est disponible dans le même nom de champ. Par exemple, pour savoir à quel corpus appartient un objet, il suffira de consulter le champ corpusName, quelque soit l'objet documentaire. Mais tous les objets documentaires ne se valant pas, certaines informations peuvent manquer pour certains, et être restitué pour d'autres, comme par exemple pour le champ pii.

En règle générale, les informations concernant le document (article ou chapitre) en lui-même sont directement indiquées par leur nom (par exemple title ou genre), alors que les informations liées à la revue ou à l'ebook doivent être précédées de host (par exemple host.title ou host.genre). Pour de plus amples détails sur la granularité ou pour voir l'ensemble des champs indexés, consultez la section qui lui est consacrée.

Pour interroger un champ particulier, il suffit d'indiquer son nom et d'ajouter : (deux points) avant la requête qui lui sera liée.

| Exemples | | -------- | ------- | | Recherche des documents contenant le terme "api" et dont un titre contient le mot "study" | https://api.istex.fr/document/?q=api AND title:study | | Recherche des documents contenant le terme "api" et dont un titre de série contient le mot "computer" | https://api.istex.fr/document/?q=api AND host.title:computer

Il est également possible de chercher sur un intervalle, avec l'utilisation des [] (crochets) et des {} (parenthèses) et du mot clé TO (en majuscules). Les crochets sont inclusifs, alors que les accolades, à l'inverse, sont exclusives. L'intervalle peut se faire sur des nombres, mais également sur des mots : il s'agit alors d'un intervalle alphabétique.

| Exemples | | -------- | ------- | | Recherche des documents contenant une date de publication entre 1900 et 1905 | https://api.istex.fr/document/?q=publicationDate:[1900 TO 1905]
https://api.istex.fr/document/?q=publicationDate:{1899 TO 1906}
https://api.istex.fr/document/?q=publicationDate:[1900 TO 1906} | | Recherche des documents contenant un terme entre "half" et "ham" dans son titre | https://api.istex.fr/document/?q=title:[half TO ham]

Pour plus de détails sur cette syntaxe, nous vous invitons à consulter la documentation officielle.

Opérateur par défaut

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q={query}&defaultOperator={AND ou OR} | | Explications | Cette option permet de sélectionner l'opérateur par défaut de l'API.
Si l'option est manquante, ce dernier sera le OR.

Par exemple, une recherche du type https://api.istex.fr/document/?q=controllability study
doit chercher tous les documents ayant au moins un de ces mots : controllability, study.

Les seuls opérateurs autorisés sont AND et OR. | | Paramètres | - &defaultOperator : l'option permettant de choisir l'opérateur par défaut,
- {AND ou OR} : l'opérateur choisi. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Recherche des documents contenant les termes "controllability" et "study" | https://api.istex.fr/document/?q=controllability study&defaultOperator=AND
https://api.istex.fr/document/?q=controllability AND study | | Recherche des documents contenant les termes "controllability" ou "study" | https://api.istex.fr/document/?q=controllability study&defaultOperator=OR
https://api.istex.fr/document/?q=controllability OR study
https://api.istex.fr/document/?q=controllability study |

Exemples classiques de recherche

Ici sont listés différents types de recherche pouvant être effectué via l'API :

Recherche par corpus

Champ concerné : corpusName:{valeur}

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q=corpusName:{valeur} | | Paramètres | - corpusName : le champ concerné,
- {valeur} : la valeur recherchée. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Recherche des documents présents dans le corpus ecco | https://api.istex.fr/document/?q=corpusName:ecco&output= | | Recherche des documents contenant le terme "chemical" dans le corpus RSC Journals | https://api.istex.fr/document/?q=chemical AND corpusName:"rsc-journals"&output=

Recherche par auteur

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q=author.name:{nom} | | Paramètres | - author.name : le champ concerné,
- {nom} : le nom recherché.| | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr)|

| Exemples | | -------- | ------- | | Recherche des documents contenant un auteur ayant pour nom "Tetsushiro" | https://api.istex.fr/document/?q=author.name:Tetsushiro&output= | | Recherche des documents contenant le terme "Mikroelement" et un auteur ayant pour nom "Friedrich" | https://api.istex.fr/document/?q=Mikroelement AND author.name:Friedrich&output=

Recherche par rédacteur

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q=host.editor.name:{nom} | | Paramètres | - host.editor.name : le champ concerné,
- {nom} : le nom recherché. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Recherche des documents contenant un rédacteur ayant pour nom "Goos" | https://api.istex.fr/document/?q=host.editor.name:Goos&output= | | Recherche des documents contenant le terme "dangerous" et ayant un rédacteur du nom de "Juris Hartmanis" | https://api.istex.fr/document/?q=dangerous AND host.editor.name:"Juris Hartmanis"&output=

Recherche par genre de document

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q=genre:{valeur} | | Paramètres | - genre : le champ concerné,
- {valeur} : la valeur recherchée. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Recherche des documents contenant un document de type "reviews" | https://api.istex.fr/document/?q=genre:reviews&output= | | Recherche des documents contenant le terme "cortex" et étant du type "Original Paper" | https://api.istex.fr/document/?q=cortex AND genre:"original paper"&output=

Recherche par genre de série

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q=host.genre:{valeur} | | Paramètres | - host.genre : le champ concerné,
- {valeur} : la valeur recherchée. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Recherche des documents contenant un document présent dans un journal | https://api.istex.fr/document/?q=host.genre:journal&output= | | Recherche des documents contenant le terme "cortex" et présent dans un livre | https://api.istex.fr/document/?q=cortex AND host.genre:book&output=

Recherche par sujet

Champ concerné : subject.value:{valeur}

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q=subject.value:{valeur} | | Paramètres | - subject.value : le champ concerné,
- {valeur} : la valeur recherchée. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Recherche des documents contenant un sujet "pigeon" | https://api.istex.fr/document/?q=subject.value:pigeon&output= | | Recherche des documents contenant un sujet avec "pigeon" et "retina" | https://api.istex.fr/document/?q=subject.value:(pigeon AND retina)&output=

Recherche par sujet de série

Champ concerné : host.subject.value:{valeur}

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q=host.subject.value:{valeur} | | Paramètres | - host.subject.value : le champ concerné,
- {valeur} : la valeur recherchée. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Recherche des documents contenant un sujet de série "statistics" | https://api.istex.fr/document/?q=host.subject.value:statistics&output= | | Recherche des documents contenant le terme "germination" et ayant un sujet de série "life sciences" | https://api.istex.fr/document/?q=germination AND host.subject.value:"life sciences"&output=

Recherche par langue

Champ concerné : language:{valeur}

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q=language:{valeur} | | Paramètres | - language : le champ concerné,
- {valeur} : la valeur recherchée. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Recherche des documents en langue allemande | https://api.istex.fr/document/?q=language:ger&output= | | Recherche des documents contenant le terme "germination" et en langue anglaise | https://api.istex.fr/document/?q=germination AND language:eng&output=

Extraction

L'API est capable de vous fournir une archive au format ZIP répondant à vos critères de recherche. Cette méthode, certes moins performante qu'un harvesting du client, vous permettra de vous assurer de la conformité des données et de leur complétude.

Pour effectuer une extraction, vous devrez agrémenter votre requête de l'option extract, qui est soumise au contrôle d'accès.
Vous pouvez demander à l'API d'extraire tout ou partie des données disponibles, en précisant le type et le format (meta-données, texte-plein, formats Mods, TEI, PDF, etc.).

Pour le moment, et pour des raisons purement techniques, le nombre de documents qu'il est possible d'extraire en une requête est limité à 10000 maximum. L'API renvoie un code d'erreur 413 en cas de dépassement. Par défaut, seuls 10 documents sont archivés si rien n'est précisé.

Syntaxe

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q={valeur}&extract | | Paramètres | - q : la requête
- extract:${typefichier}[${formats}] : la sélection des type et formats de fichiers à extraire | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

Plus de détails sur la syntaxe extract:${typefichier}[${formats}] :

${typefichier} est une liste parmi les valeurs metadata, fulltext, enrichments, cover,annexes, séparée par le caractère ;.
${formats} correspond à la liste des formats de fichiers (au sens "mimetype"). Il peut être renseigné pour chaque type (metadata, fulltext...). Pour cela, la liste des formats est mentionnée entre crochets [...] et séparée par des virgules.
si extract est utilisé seul, l'ensemble des fichiers disponibles est extrait.

| Exemples | | -------- | ------- | | Extraction de toutes les documents relatifs au terme "brain" | https://api.istex.fr/document/?q=brain&extract&output=* | | Extraction de tous les fichiers de méta-données et de plein-texte correspondant au terme "brain"| https://api.istex.fr/document/?q=brain&extract=metadata;fulltext | Extraction des méta-données en Mods uniquement, du plein-texte en PDF et TEI, et toutes les annexes pour le terme "brain"| https://api.istex.fr/document/?q=brain&extract=metadata[mods];fulltext[pdf,tei];annexes

Vous pouvez aussi utiliser les paramètres de recherche classiques from, size, rankBy, sortBy et randomSeed, ce qui vous permettra d'influencer le nombre et l'ordre des documents archivés.

A propos de l'archive générée

L'archive Zip qui est générée suit une organisation particulière. Les documents sont ventilés dans l'arborescence à 5 niveaux suivante :

Un fichier manifest.json contenant des éléments d'informations sur la requête utilisées pour l'extraction
3 niveaux avec des sous-répertoires nommés avec l'un des 16 caractères 0, 1... 9, A... F
un 4ème niveau de sous-répertoires, nommés selon l'identifiant Istex idIstex et contenant un fichier ${idIstex}.json avec l'ensemble du document (métadonnées + fulltext) au format JSON
le 5ème niveau se compose des sous-répertoires fulltext, metadata, annexes et covers (absents ou présents selon les cas) contenant les formats de fichiers demandés lors de l'extraction.