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

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

### Options

```txt
    -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

```bash
    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

```txt
    -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
    -s  indique le jeton d’authentification “SID” obtenu avec le programme
        “WosConnect.sh”
```

### Autres options

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

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

```bash
    -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](http://help.incites.clarivate.com/wosWebServicesExpanded/appendix1Group/wosfieldNameTable.html).

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


### Usage

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

### Options

```txt
    -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
```


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

```bash
    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 

```txt
    -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 

```txt
    -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

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

### Options

```txt
    -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 envoyant les 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. 

```bash
    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

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

### Options

```txt
    -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](https://fr.wikipedia.org/wiki/Lex_(logiciel) qui se compile avec `flex` et `gcc`. Les différentes étapes sont : 

```bash
    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 : 

```bash
    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”.