api-wos
===============

Scripts pour interroger l’API WoS (Web of Science) et télécharger un corpus de notices en utilisant soit le protocole REST, soit le protocole SOAP. 


## REST

L’interrogation et le téléchargement d’un corpus se fait sans avoir à ouvrir une session et l’authentification se fait uniquement à l’aide d’une clé. 
Les différentes étapes se font avec un script `bash` dédié : 

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

Les notices obtenue peuvent être au format JSON ou au format XML au choix.


## SOAP

Avec le protocole SOAP, il est nécessaire de se connecter et d’ouvrir une session pour pouvoir interagir avec l’API WoS. 
L’authentification se fait avec un nom d’utilisateur et un mot de passe et il y a 5 étapes différentes, chacune réalisée avec un script `bash` dédie :

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

Les notices obtenues sont uniquement au format JSON.


## Tables WoS

Certains paramètres de l’interrogation de l’API et du téléchargement de notices sont limités à une liste finie ou sont sous forme de codes. 
Cela concerne :

 - les bases WoS
 - les champs visualisables
 - les critères de tri des notices

La première table n’est utile que pour l’interrogation alors que les deux suivantes sont utiles si on veut modifier l’ordre des notices du corpus 
ou la liste des champs affichés. Comme on peut déjà décharger des notices lors de l’interrogation, il est important dans ce cas d’utiliser 
les mêmes options de tri et/ou de visualisation lors du téléchargement. 


### 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ères 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).