Sélection des champs renvoyés

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q={query}&output={liste des champs} | | Explications | Cette option permet de sélectionner les champs renvoyés lors de l'affichage des résultats.
Si l'option est manquante, les résultats afficheront leur champ title.
Dans tous les cas, les champs id et score seront présents.

La liste des champs est séparée par des , (virgules).

Il est possible de demander l'affichage :
- de l'ensemble des champs disponibles avec le caractère * (étoile),
- de l'ensemble des fichiers fulltext disponibles avec le mot-clé fulltext,
- de l'ensemble des fichiers metadata disponibles avec le mot-clé metadata,
- de l'ensemble des enrichissements disponibles avec le mot-clé enrichments,
- de l'ensemble des annexes disponibles avec le mot-clé annexes.

Si, pour un résultat, le champ n'est pas affiché, cela indique que le résultat en question n'a pas ce champ renseigné.| | Paramètres | - &output : l'option permettant de définir la liste des champs,
- {liste des champs} : la liste en question, séparée par des virgules. | | Code de retour | - 200 si OK,
- 501 si le champ demandé n'est pas disponible,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Récupération des champs title et fulltext sur l'ensemble des résultats | https://api.istex.fr/document/?q=&output=title,fulltext | | Récupération de tous les champs disponibles sur l'ensemble des résultats | https://api.istex.fr/document/?q=&output=* |

Choix du type de scoring

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q={query}&rankBy={type de ranking} | | Explications | Chaque résultat affiche un champ score.
Cette option permet de sélectionner le type de score renvoyé lors de l'affichage des résultats.
Si l'option est manquante, le score sera basé sur l'algorithme BM25 d'elasticsearch, selon la requête demandée.

Il est possible de demander un score relevé par la qualité avec le mot-clé qualityOverRelevance.
Le calcul du score de qualité est expliqué ci-dessous.

Il est possible de demander un score aléatoire avec le mot-clé random.
Deux requêtes successives avec un score aléatoire renverront des résultats dans un ordre différent.
Une requête avec score aléatoire génère en plus un code unique, permettant de retrouver cet ordre plus tard.
Ce code est visible dans les champs nextPageURI, prevPageURI, firstPageURI ou lastPageURI.
L'option indiquant le code et permettant de retrouver le même ordre est &randomSeed={code}.| | Paramètres | - &rankBy : l'option permettant de définir le type de score,
- {type de ranking} : mot-clé désignant le type de score spécial (qualityOverRelevance, random). | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Résultats ayant le mot "agile" avec un affichage relevé par qualité | https://api.istex.fr/document/?q=agile&rankBy=qualityOverRelevance | | Résultats ayant le mot "agile" avec un affichage aléatoire | https://api.istex.fr/document/?q=agile&rankBy=random |

Calcul du score de qualité

Chaque document indexé possède un score calculé par rapport à certains indices de qualité, présents dans le champ qualityIndicators. Ce score est noté sur une échelle de 10 points.

La formule est la suivante :

  • 5 points sont consacrés au nombre de mots dans le fulltext : min(5, 5 x pdfWordCount / 5000)
    • On estime qu'un fulltext ayant 5000 mots ou plus est de qualité excellente.
  • 3 points sont consacrés au nombre de mots dans l'abstract : min(3, 3 x abstractWordCount / 250)
    • On estime qu'un abstract ayant 250 mots ou plus est de qualité excellente.
  • 2 points sont consacrés à la version du PDF :
    • inférieur à 1.3 = 0 point
    • version 1.4 = 0.5 point
    • version 1.5 = 1 point
    • version 1.6 = 1.5 points
    • supérieur à 1.7 = 2 points

Ce score et cette formule sont susceptibles d'évoluer dans le temps avec l'ajout de nouveaux indices de qualité.

Tris basés sur le mapping

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q={query}&sortBy={liste des champs} | | Explications | Cette option permet de sélectionner un ou des tris basés sur les champs disponibles.
Si l'option est manquante, aucun tri n'est effectué.

La liste des champs est séparée par des , (virgules).

Attention, l'ordre des tris est très important :
un tri du type sortBy=x,y demandera à l'API d'effectuer d'abord un tri selon x, puis de trier cet ordre selon y.

Il existe plusieurs paramétrages possibles :
- x : renvoie les résultats triés selon le champ x en ordre ascendant (ordre par défaut)
- x[asc] : renvoie les résultats triés selon le champ x en ordre ascendant
- x[desc] : renvoie les résultats triés selon le champ x en ordre descendant| | Paramètres | - &sortBy : l'option permettant de définir les tris à effectuer,
- {liste des champs} : la liste en question, séparée par des virgules. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Affichage de l'ensemble des documents triés selon le champ host.copyrightDate | https://api.istex.fr/document/?q=&sortBy=host.copyrightDate&output=host.copyrightDate | | Affichage de l'ensemble des documents triés selon le champ host.copyrightDate, en ordre descendant | https://api.istex.fr/document/?q=&sortBy=host.copyrightDate[desc]&output=host.copyrightDate | | Affichage de l'ensemble des documents triés selon le champ host.copyrightDate, puis le champ genre | https://api.istex.fr/document/?q=*&sortBy=host.copyrightDate,genre.raw&output=host.copyrightDate,genre |

Paramètres de pagination

Les paramètres de pagination se basent sur les deux options from et size qui s'utilisent et se combinent comme suit :

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q={query}&from={position} | | Explications | Cette option permet d'indiquer le numéro de départ du premier résultat renvoyé.
Si l'option est manquante, l'affichage commencera au premier résultat.

La position est un entier.
Si ce nombre dépasse le nombre de résultats, la page n'affichera aucun résultat.| | Paramètres | - &from : l'option permettant de définir le numéro de départ,
- {position} : le numéro de départ en question. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q={query}&size={nombre} | | Explications | Cette option permet d'indiquer le nombre de résultats renvoyés par page.
Si l'option est manquante, chaque page affichera 10 résultats.

Le nombre est un entier ne pouvant pas dépasser 5000.
Dans le cas contraire, ce nombre sera descendu automatique à 5000.| | Paramètres | - &from : l'option permettant de définir le numéro de départ,
- {position} : le numéro de départ en question. | | Code de retour | - 200 si OK,
- 500 en cas de problème (dans ce cas, contacter api-bug@listes.istex.fr) |

| Exemples | | -------- | ------- | | Récupération des 7 premiers résultats pour le terme "controllability" | https://api.istex.fr/document/?q=controllability&size=7
https://api.istex.fr/document/?q=controllability&from=0&size=7 | | Récupération des résultats 3 à 7 pour le terme "controllability" | https://api.istex.fr/document/?q=controllability&from=3&size=4 |

Une fois cette requête effectuée, il est possible de naviguer dans les résultats grâce aux champs suivants, présents dans la réponse de l'API :

  • firstPageURI : fournit l'URI permettant d'atteindre la toute première page.
  • lastPageURI : fournit l'URI permettant d'atteindre la toute dernière page.
  • prevPageURI : fournit l'URI permettant d'atteindre la page précédente. N'est pas présent si la page actuelle est la première page.
  • nextPageURI : fournit l'URI permettant d'atteindre la page suivante. N'est pas présent si la page actuelle est la dernière page.

!!! Notes importantes !!!!

  • Il est impossible de parcourir les résultats au-delà de la 10 000ème réponse. En d'autres termes, la somme des paramètres from et size ne doit jamais dépasser 10 000. Si vous avez besoin de dépasser ce seuil, vous devez utiliser la pagination de type scroll présentée ci-dessous.

  • Le paramètre lastPageURI est par conséquent déprécié et ne doit plus être utilisé

Pagination de type "scroll"

Pour parcourir de grands ensembles de résultats, la pagination classique ne peut pas être utilisée. Il s'agit d'une limitation technique pour préserver les performances du moteur de recherche.

Il convient alors d'utiliser la fonctionnalité de "scrolling", qui permet de parcourir d'un bout à l'autre un ensemble de résultats. Dans ce mode de parcours, il n'est pas possible de "revenir en arrière" dans les résultats, d'où l'absence de notion de page.

Le principe d'utilisation est le suivant :

  • Lors du premier appel de la recherche, le paramètre d'URL scroll est renseigné, ce qui active ce mode de parcours
  • L'API renvoie le premier groupe de résultats, accompagné d'un identifiant scrollId
  • Pour accéder à la suite des résultats, vous devez relancer la requête initiale accompagnée du paramètre scrollId, ce qui permet à l'API savoir à quel parcours et jeu de résultats se référer.

| Syntaxe | |------------ | ------------- | | URI | https://api.istex.fr/document/?q={query}&scroll={durée}&scrollId={identifiant} | | Explications | Cette option permet d'activer le mode scroll.
Dans ce mode, une sorte de "session" de parcours est initiée et maintenue active pendant temps limité,
à l'issue duquel les résultats ne peuvent plus être parcourus. | | Paramètres | - &scroll : l'option permettant de définir la durée pendant laquelle la liste des résultats reste "active".
Ce délai est formé d'un nombre entier suivi des caractères d, h, m, s ou ms.
La valeur par défaut est 30s.
Ce délai est remis à zéro à chaque déplacement dans les résultats de la session courante.| | Paramètres | - &scrollId : l'option permettant de spécifier la session (le jeu de résultats) en cours de parcours.| | Code de retour | - 200 si OK,
- 404 si le délai a été dépassé (équivaut à : contexte scrollId non trouvé)
- 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,
    "scroll": délai d'activation pour la session de scroll
    "scrollId": identifiant de la session de scroll
    "nextScrollURI": URL de navigation dans la suite des résultats
    "noMoreScrollResults": booléen permettant de savoir s'il reste des résultats
    "hits": [
        groupe de résultats courant 
        ....
    ]
}