Newer
Older
api-wos / REST / README.md

REST

Scripts pour se connecter à l’API WoS (Web of Science) pour l’interroger et télécharger un corpus de notices, au format JSON ou au format XML, en utilisant le protocole REST. Il n’y a pas de session à proprement parler, mais se passe en 2 étapes avec un script bash dédié pour chacune de ces étapes :

Étapes Scripts
Interrogation de l’API rWosQuery.sh
Téléchargement des notices rWosRetrieve.sh

Dans le cas particulier d’une recherche à partir d’une liste de DOIs, on utilise le script rWosSearchByDoi.sh qui fait à la fois l’interrogation de l’API et le téléchargement des notices, remplaçant ainsi les scripts rWosQuery.sh et rWosRetrieve.sh.

Ces scripts ont besoin pour fonctionner de trois programmes qui sont généralement présents dans les distributions Unix/Linux :

  • curl
  • jq
  • xmllint

Pour tous ces scripts, toutes les informations renvoyées par le programme curl sur la sortie standard ou sur l’erreur standard sont conservées dans deux fichiers, respectivement WosApiOut.json ou WosApiOut.xml (suivant le format des notices), et WosApiErr.txt.

rWosQuery.sh

Ce script permet l’interrogation de l’API WoS à l’aide d'une clé chiffrée. Par souci de sécurité, il n’y a pas d’option pour la clé en ligne de commande. Elle sera demandé par la suite de façon plus sûre. Par défaut, l’interrogation se fait sur l’ensemble des bases WoS et retourne un numéro de requête (queryId), le nombre de notices trouvées, le nombre total de notices dans les bases WoS interrogées ainsi que 5 notices complètes. Il est possible de limiter la recherche à certaines bases WoS avec l’option “-b”, on peut choisir de ne garder que certains champs dans les notices grâce à l’option “-f” et on peut modifier l’ordre de tri des notices avec l’option -t.

Usage

    rWosQuery.sh -q 'requête' [ -r (résultats|-) ] [ -n nb_notices ]
                 [ -[cmp] début:fin ] [ -l [0-9]+[DWMY] ] [ -b [WOS:]base ]*
                 [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ]
                 [ -j cookie_jar ] [ -ix ]
    rWosQuery.sh -h

À noter que les options -c, -l, -m et -p be sont pas compatibles entre elles et on ne peut en utiliser au plus qu'une seule. Les valeurs possibles pour les options -b, -f et -t sont données dans les tables WoS de la page rincipale.

Options principales

    -c  limite la recherche dans la base de données aux dates de création
        des notices indiquées sous la forme aaaa-mm-jj:aaaa-mm-jj (comme par
        exemple, “2000-01-01:2020-07-31”)
    -h  affiche cette aide
    -l  limite la recherche dans la base de données aux dates de chargement
        des notices indiquées sous la forme d’un nombre de jours (D), de
        semaines (W), de mois (M) ou d’années (Y). Les valeurs acceptées vont
        de “0D” à “6D”, de “1W” à “52W”, de “1M” à “12M” et de “0Y” à “10Y”
    -m  limite la recherche dans la base de données aux dates de modification
        des notices indiquées sous la forme aaaa-mm-jj:aaaa-mm-jj (comme par
        exemple, “2000-01-01:2020-07-31”)
    -p  limite la recherche dans la base de données aux dates de publication
        indiquées sous la forme aaaa-mm-jj:aaaa-mm-jj (comme par exemple,
        “2000-01-01:2020-07-31”)
    -r  indique le nom du fichier où placer les notices téléchargées (mettre
        un tiret pour indiquer la sortie standard)
    -q  fournit la requête à envoyer (entre simples ou doubles quotes si
        elle contient des espaces ou des caractères spéciaux)
    -x  indique que les notices doivent être en XML au lieu de JSON, le format
        par défaut

Autres options

    -b  limite la recherche à une ou plusieurs bases (e.g. “WOS:SCI”).
        Cette option est répétitive et “WOS:” est facultatif (par défaut,
        la recherche se fait sur l’ensemble du WoS)
    -f  limite les champs présents dans les notices téléchargées. Cette
        option est répétitive (par défaut, tous les champs sont présents)
    -i  ajoute dans la réponse de l’API la liste des identifiants WoS des
        notices retournées (5 par défaut ou valeur de l’option “-n”)
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -n  indique le nombre de notices, entre 0 et 100, à retourner (5 par
        défaut)
    -t  trie les résultats sur un champ (nom abrégé à 2 majuscules) de
        façon croissante (A) ou décroissante (D) ou par pertinence (RS)
        forcément décroissante

rWosRetrieve.sh

Ce script permet de télécharger les notices trouvées lors de l’interrogation de l’API WoS en utilisant la clé d’identification (demandée hors ligne de commande, par sécurité) et le numéro de requête (queryId) obtenu à l’étape précédente. En cas d’interruption du transfert, il est possible de reprendre le téléchargement là où il s'est arrêté en indiquant un nouveau numéro de départ (option “-o”). Si vous avez utilisé les options -f et/ou -t lors de l’interrogation de l’API, vous devez utiliser les mêmes options avec les mêmes valeurs pour décharger le corpus de notices Si vous recevez un message signalant une limitation de la bande passante (bandwidth throttling), vous pouvez modifier le délai entre deux itérations (1 seconde par défaut) avec la variable d’environnement WOS_DELAY. Par exemple, pour passer à un délai de 3 secondes :

    export WOS_DELAY=3

Usage

    rWosRetrieve.sh -q queryId -n nb_notices -r (résultats|-) [ -o offset ] 
                    [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ]
                    [ -j cookie_jar ] [ -ix ]
    rWosRetrieve.sh -h

Options

    -f  limite les champs présents dans les notices téléchargées. Cette
        option est répétitive (par défaut, tous les champs sont présents)
    -h  affiche cette aide
    -i  ajoute dans la réponse de l’API la liste des identifiants WoS des
        notices retournées
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -n  indique le nombre total de notices WoS à télécharger (la valeur
        maximale est donnée par le programme envoyant la requête à l’API
        WoS)
    -o  indique à partir de quel numéro (offset), on veut télécharger les
        notices, en particulier pour reprendre un téléchargement après un
        problème de connexion (1 par défaut)
    -q  indique le numéro de la requête “queryId” dont on veut télécharger
        les résultats
    -r  indique le nom du fichier résultat (pour la sortie standard, utiliser
        le tiret “-” comme argument de l’option)
    -t  trie les résultats sur un champ (nom abrégé à 2 majuscules) de
        façon croissante (A) ou décroissante (D) ou par pertinence (RS)
        forcément décroissante
    -x  indique que les notices doivent être en XML au lieu de JSON, le format
        par défaut

rWosSearchByDoi.sh (en cours de réécriture)

Ce script permet à la fois l’interrogation de l’API WoS à partir d’une liste de DOIs et le téléchargement des notices trouvées en utilisant la clé d’identification. Contrairement au script rWosQuery.sh, on n’a pas d’options pour limiter la recherche par période ou par base. On n’a pas non plus d’option de tri parce que la recherche se fait par paquet de 100 DOI maximum et le tri se ferait au sein de chaque paquet au lieu de se faire sur l’ensemble du corpus. En fait, on récupère les notices dans l’ordre des DOI.

Usage

    rWosSearchByDoi.sh -d (fichier|-) -r (résultats|-) [ -f champs ]*
                       [ -j cookie_jar ] [ -ix ]
    rWosSearchByDoi.sh -h

Options principales

    -d  indique le nom du fichier avec la liste des DOIs à chercher. Si on
        a un tiret “-” en argument, la liste de DOIs est lue sur l’entrée
        standard
    -f  limite les champs présents dans les notices téléchargées. Cette
        option est répétitive (par défaut, tous les champs sont présents)
    -h  affiche cette aide
    -i  ajoute dans la réponse de l’API la liste des identifiants WoS des
        notices retournées
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
    -r  indique le nom du fichier résultat (pour la sortie standard, utiliser
        le tiret “-” comme argument de l’option)
    -x  indique que les notices doivent être en XML au lieu de JSON, le format
        par défaut