Scripts pour interroger l’API WoS et télécharger un corpus de notices

README.md Mise à jour de README.md 3 months ago
WosClose.sh Modification surtout cosmétique des scripts 3 months ago
WosConnect.sh Modification surtout cosmétique des scripts 3 months ago
WosDecode.sh Mise à jour des scripts 4 months ago
WosQuery.sh Correction de la requête curl de WosQuery 3 months ago
WosRetrieve.sh Nouvelle version de WosRetrieve 3 months ago
WosSearchByDoi.sh Mise à jour des scripts 4 months ago
decode_wos.l Version 1.0 4 months ago
README.md

api-wos

Scripts pour se connecter à l’API WoS (Web of Science) pour l’interroger et télécharger un corpus de notices. Chaque session se passe en 5 étapes avec un script bash dédié à chacune de ces étapes :

Étapes Scripts
Connexion à l’API WosConnect.sh
Interrogation de l’API WosQuery.sh
Téléchargement des notices WosRetrieve.sh
Déconnexion WosClose.sh
Extraction des notices WosDecode.sh

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

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

  • base64
  • curl
  • xmllint

En plus, le dernier script a besoin du programme C decode_wos dont le programme source, decode_wos.l, doit être compilé avec flex et gcc.

Pour les scripts communiquant avec l’API, c’est-à-dire les 4 premiers, 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.txt et WosApiErr.txt.

WosConnect.sh

Ce script permet la connexion à l’API WoS à l’aide d'un nom d’utilisateur et un mot de passe. En cas de succès, le script renvoie un identifiant de session (SID) à utiliser lors des étapes suivantes. Par souci de sécurité, il n’y a pas d’option pour le mot de passe en ligne de commande. Il sera demandé par la suite de façon plus sûre.

Usage

    WosConnect.sh -u utilisateur [ -c cookies.txt ]
    WosConnect.sh -h

Options

    -c  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -h  affiche cette aide
    -u  indique le nom de l’utilisateur (login).

WosQuery.sh

Ce script permet l’interrogation de l’API WoS à l’aide d’une requête en utilisant l’identifiant SID. 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” et on peut choisir de ne garder que certains champs dans les notices grâce à l’option “-f”. À noter que quelque soit le nombre de notices trouvées, on ne peut en télécharger que 100 000 au maximum. Au-delà, il faut faire plusieurs requêtes en indiquant, avec l’option “-p”, des périodes de temps successives. Les dates de début et de fin de période correspondent aux dates auxquelles les notices sont ajoutées à la base. Pour les personnes faisant une veille continue sur WoS, il est également possible de demander à ne considérer que les notices des 1, 2 ou 4 dernières semaines, toujours avec l’option “-p”.

Usage

    WosQuery.sh -s sid -q requête [ -p (début:fin|[124]week) ]
                [ -b [WOS:]base ]* [ -f champs ]*  [ -t CH:[AD] ]
                [ -n notices ] [ -c cookies.txt ] [ -i ]
    WosQuery.sh -h

Options principales

    -h  affiche cette aide 
    -p  limite la recherche dans la base de données à la période indiquée
        sous forme aaaa-mm-jj:aaaa-mm-jj (e.g., “2000-01-01:2020-07-31”)
        ou sous forme “1week”, “2week” ou “4week” 
    -q  fournit la requête à envoyer (entre simples ou doubles quotes si 
        elle contient des espaces ou des caractères spéciaux) 
    -s  indique le jeton d’authentification “SID” obtenu avec le programme
        d’authentification à l’API WoS

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)
    -c  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -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”)
    -n  indique le nombre de notices, entre 1 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 pertinene (RS)
        forcément décroissante

Bases WoS

Par défaut, l’interrogation de l’API se fait sur l’ensemble des bases WoS, mais vous pouvez décider de n’utiliser qu'une base ou qu’un ensemble limité de bases avec l’option “-b”. Cette option est répétitive, mais vous pouvez également faire une liste de bases séparées par des virgules (sans espace) ou faire une liste de bases séparés par des espaces, mais le tout entre simples ou doubles quotes. Comme toutes ces bases ont le même préfixe WOS:, vous pouvez vous dispenser de le mettre. Dans l’exemple suivant où on limite la requête aux bases en SHS, les différentes façons d’écrire cette option donnent le même résultat.

    -b SSCI -b ISSHP -b BHCI
    -b SSCI,ISSHP,BHCI
    -b "SSCI ISSHP BHCI"
    -b WOS:SSCI,WOS:ISSHP,WOS:BHCI

Dans le tableau suivant, vous avez la liste des bases avec leur intitulé.

Bases Intitulés
WOS:SCI Science Citation Index Expanded
WOS:SSCI Social Sciences Citation Index
WOS:AHCI Arts & Humanities Citation Index
WOS:ISTP Conference Proceedings Citation Index - Science
WOS:ISSHP Conference Proceedings Citation Index - Social Sciences
WOS:IC Index Chemicus
WOS:CCR Current Chemical Reactions
WOS:BSCI Book Citation Index - Science
WOS:BHCI Book Citation Index - Social Sciences and Humanities
WOS:ESCI Emerging Sources Citation Index

Champs visualisables

Il est possible avec l’option “-f” de limiter le nombre de champs présents dans les notices. Mais, plutôt que des noms de champ très spécifiques, on a souvent des rubriques. Ainsi “titles” représentent tous les titres : titre du document, titre de la revue ou titre du livre.

Comme pour l’option “-b”, l’option “-f” est répétitve et on peut regrouper les champs en les séparant par des virgules, sans espace, ou en les séparant par des espaces, mais entre simpls ou doubles quotes. Dans l’exemple suivant, les différentes façons d’écrire la requête donnent le même résultat.

    -f titles -f names -f pub_info -f identifiers
    -f titles,names,pub_info,identifiers
    -f "titles names pub_info identifiers"

Dans le tableau suivant, vous avez la liste des différents champs visualisables. Vous pouvez retrouver l’équivalence entre ces intitulés et les noms de champs correspondants sur le site de Web of Science.

Champs visualisables Champs visualisables Champs visualisables
abstract email_addr names
addresses full_name organizations
address_spec fund_text page
book_chapters grant pub_info
conf_date headings refs
conf_host identifiers reprint_contact
conf_locations ids sponsors
conf_title keywords subjects
contributor keywords_plus titles
doctypes language UID

Critère de tri

Enfin, il est possible avec l’option “-t” de trier les résultats en fonction d'un champ, désigné par une abréviation à 2 lettres majuscules, dans le sens croissant (A) ou décroissant (D). Le tableau suivant donne la liste de ces champs et leur abréviation.

Abréviation Nom du champ
AU Author
CF Conference title
CG Page
CW Source
CV Volume
LC Local count
LD Load date
PG Page
PY Publication year
RS Relevance
SO Source
TC Time cited
VL Volume

À noter que les champs RS et TC ne peuvent être triés que dans le sens décroissant (D).

WosRetrieve.sh

Ce script permet de télécharger les notices trouvées lors de l’interrogation de l’API WoS en utilisant l’identifiant SID 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”). Au cas où un paquet de notices a une taille trop élevée et se retrouve tronqué, vous pouvez relancer le téléchargement avec un nombre de notices plus petit (l’option “-t”). De même, 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

    WosRetrieve.sh -s sid -q queryId -n nb_notices -r résultat
                   [ -o offset ] [ -t taille ] [ -c cookies.txt ]
    WosRetrieve.sh -h

Options

    -c  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -h  affiche cette aide
    -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)
    -s  indique le jeton d’authentification “SID” obtenu avec le programme
        d’authentification à l'API WoS
    -t  indique le nombre de notices (entre 1 et 100) à télécharger à chaque 
        itération (100 par défaut)

WosSearchByDoi.sh

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 l’identifiant SID. Fondamentalement, les options sont les mêmes que pour le script WosQuery.sh. La seule différence, c’est qu’on a un fichier avec les DOIs en entrée et un fichier de résultats en sortie.

Usage

    WosSearchByDoi.sh -s sid -d (fichier|-) -r (résultats|-)
                      [ -p (début:fin|[124]week) ] [ -b [WOS:]base ]*
                      [ -f champs ]* [ -c cookies ] [ -i ]
    WosSearchByDoi.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
    -h  affiche cette aide
    -p  limite la recherche dans la base de données à la période indiquée
        sous forme aaaa-mm-jj:aaaa-mm-jj (e.g., “2000-01-01:2020-07-31”)
        ou sous forme “1week”, “2week” ou “4week”
    -r  indique le nom du fichier résultat (pour la sortie standard, utiliser
        le tiret “-” comme argument de l’option)
    -s  indique le jeton d’authentification “SID” obtenu avec le programme
        d‘authentification à l‘API WoS

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)
    -c  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -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 à chaque itération

WosClose

Ce script permet de terminer une session d’interrogation de l’API WoS, après une ou plusieurs itérations de reqêtes et de téléchargements. À noter que l’identifiant de session (SID) a une durée de vie limitée, donc, la session s’arrêtera de toute façon.

Usage

    WosClose.sh -s sid [ -c cookies.txt ]
    WosClose.sh -h

Options

    -c  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -h  affiche cette aide
    -s  indique le jeton d’authentification “SID” obtenu avec le programme
        d’authentification à l'API WoS

WosDecode.sh

Que se soit en utilisant le script WosRetrieve.sh ou le script WosSearchByDoi.sh, le fichier de résultats est souvent la concaténation de plusieurs fichiers. Dans chacun de ses fichiers, les notices sont encodées au sein de l’élément records. Le script WosDecode.sh permet de remettre les notices au format XML et d’en faire un fichier « bien formé ». Il utilise le programme C decode_wos qu’il faut compiler à partir du fichier source decode_wos.l .

Ce script peut traiter plusieurs fichiers en même temps soit en les listant avec l’option “-f”, soit en les envoyant par l’entrée standard, soit par un mixte des deux. Par exemple, si on a 3 fichiers (fic1.xml, fic2.xml et fic3.xml) que l’on veut réunir en un seul fichier final, on peut utiliser les commandes suivantes qui donnent toutes le même résultat.

    WosDecode.sh -f fic1.xml -f fic2.xml -f fic3.xml
    WosDecode.sh -f fic1.xml,fic2.xml,fic3.xml
    WosDecode.sh -f "fic1.xml fic2.xml fic3.xml"
    cat fic1.xml fic2.xml fic3.xml | WosDecode.sh -f -
    cat fic2.xml | WosDecode.sh -f fic1.xml,-,fic3.xml

Usage

    WosDecode.sh -f (fichier[,fichier]*|-) [ -p programme ] [ -s sortie ]
    WosDecode.sh -h

Options

    -f  indique le nom du ou des fichiers à traiter. Cette option est
        répétitive. Vous pouvez également utiliser une liste de fichiers
        séparés par des virgules (mais sans espace) ou mettre un tiret
        si les données sont envoyées sur l’entrée standard
    -h  affiche cette aide
    -p  indique où trouver le programme “decode_wos” s’il n’est pas dans
        un des répertoires donnés par la variable $PATH
    -s  indique le nom du fichier de sortie. Sinon, les données sont
        envoyées sur la sortie standard

decode_wos

Programme C qui permet d’ajouter des sauts de ligne dans les fichiers reçus de l’API WoS tout en décodant les entités caractères de façon à avoir des notices individualisées au format XML. Comme chaque notice est sur une ligne, il devient alors possible de les filtrer et de les réunir en un seul fichier.

Compilation

Le programme source, decode_wos.l, est un fichier Lex qui se compile avec flex et gcc. Les différentes étapes sont :

    flex -t decode_wos.l > decode_wos.c
    gcc -c -o decode_wos.o decode_wos.c
    gcc decode_wos.o -lfl -o decode_wos

Sous MacOs, la dernière commande est :

    gcc decode_wos.o -ll -o decode_wos

Vous pouvez déplacer le programme decode_wos dans un des répertoires donnés par la variable globale $PATH ou indiquer sa position au script WosDecode.sh avec l’option “-p”.