Formation Médial Nancy, le 22 juin 2017.

1. LES API DE RECHERCHE DE HAL
Nancy, 22 juin 2017
Université de Lorraine
Médial - centre de formation aux carrières des bibliothèques - Grand Est
Raphaël Tournoy

2. HAL - https://hal.archives-ouvertes.fr
L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion d'articles
scientifiques de niveau recherche, publiés
ou non, et de thèses.
TEL - https://tel.archives-ouvertes.fr
TEL (thèses-en-ligne) promotion de
l'auto-archivage en ligne des thèses de
doctorat et (HDR).
Sciencesconf.org -
https://www.sciencesconf.org
Plateforme Web ouverte aux organisateurs
de colloques, workshops ou réunions
scientifiques.
MédiHAL -
https://medihal.archives-ouvertes.fr
MédiHAL, archive ouverte d’images
scientifiques et des documents
iconographiques de science.
Episciences.org - https://episciences.org
Plateforme d'épi-revues
HELOISE - http://heloise.ccsd.cnrs.fr
Politique des éditeurs en matière de
diffusion en open access des publications
scientifiques.
Créée en 2000
Missions :
Développement des archives ouvertes
pour la communauté ESR ainsi que des
services connexes
16 personnes
Basée à Villeurbanne (Rhône)
Partenaire de projets européens :
MedOANet, DARIAH-EU, PEER
Equipex DILOH, ANR Campus AAR
https://www.ccsd.cnrs.fr/
2

3. API : Application Programming Interface
3
interface de programmation applicative
pour la communication de logiciel à logiciel
API de recherche de HAL = service web de type REST

4. Du dépôt à l’API
4

5. DÉPÔT ; INDEXATION ; RÉPLICATION ; MISE EN LIGNE
5
Dépôt
Indexation
Réplication
Mise en ligne
Modération

6. TYPES D’API DISPONIBLES https://api.archives-ouvertes.fr/
6

7. API de recherche
Contenus disponibles ; Pré-requis techniques ; Syntaxe
7

8. • API Recherche HAL = documents en ligne
• API Recherche Référentiels :
• Auteurs
• Structures de recherche
• Domaines
• Liste de métadonnées
• Revues
• Projets ANR
• Projets européens
• Affiliations des auteurs
• Types de documents
• Métadonnées
API - RECHERCHE : CONTENUS DISPONIBLES
Via les API de type Solr vous
accédez aux même
données/fonctionnalités que
le CCSD
8

9. • Uniquement client http (navigateur web, cURL,
bibliothèque logicielle, ...)
PRÉ-REQUIS TECHNIQUES
9

10. • URL dans le navigateur :
• Point d’accès
• 1er paramètre précédé de ?
• paramètre = valeur
• paramètres séparés par &
SYNTAXE D’UNE REQUÊTE API WEB
10
https://api.archives-ouvertes.fr/ref/structure/
?q=lorraine
&wt=xml
&rows=5
https://api.archives-ouvertes.fr/ref/structure/?q=lorraine&wt=xml&rows=5

11. API des référentiels
https://api.archives-ouvertes.fr/docs/ref
11

12. LES RÉFÉRENTIELS https://api.archives-ouvertes.fr/docs/ref
12

13. • Types de dépôts par instance
• Métadonnées par type de dépôt
• Données de type liste fermée
• Données de type complexes
QUELS TYPES DE RÉFÉRENTIELS ?
13

14. • Tous les modèles de données sont
accessibles via l’API
• //api.archives-ouvertes.fr/ref/referentiel
• Format de réponse SOLR (type)
• <reponse>
• <result …>
• Les formats de sortie json ou xml
RECHERCHE
14

15. Référentiels
Exemples d’utilisation
Types de dépôts par instance
Métadonnées par type de dépôt
Données de type liste fermée
15

16. INSTANCE : LES PORTAILS
Comment obtenir la liste des portails de HAL où déposer ?
https://api.archives-ouvertes.fr/r
ef/doctype/?wt=json
Format JSON /?wt=json
16

17. DOCTYPE : TYPES DE DOCUMENTS
Exemple : Types de document acceptés sur TEL ( instance_s=tel )
Format JSON
17

18. METADATA : MÉTADONNÉES PAR TYPE DE DOCUMENT
https://api.archives-ouvertes.fr/ref/metadata/?instance_s=univ-lorraine&docType_s=ART&wt=xml
instance_s=univ-lorraine
(portail : Université de
Lorraine)
docType_s=ART
(Type de document : Article)
18

19. Listes de métadonnées + nombre de valeurs disponibles
METADATALIST : MÉTADONNÉES DE TYPE LISTE FERMÉE
Métadonnée audience = 3 valeurs possibles
19

20. METADATALIST :
LISTE DES MÉTADONNÉES DE TYPE LISTE FERMÉE
Quelles sont les valeurs acceptées pour la métadonnée AUDIENCE ?
https://api.archives-ouvertes.fr/ref/metadatalist/?q=metaName_s:audience
20

21. Auteurs ; Structures ; Domaines ; Revues ; Projets ANR ; Projets
Européens
Référentiels
Types complexes
21

22. TYPES COMPLEXES
AUTEURS ; STRUCTURES ; DOMAINES ; REVUES ; PROJETS ANR ; PROJETS EUROPÉENS
Consultation publique HTML : https://aurehal.archives-ouvertes.fr/
22

23. EXEMPLE STRUCTURE DANS AURÉHAL
23

24. API STRUCTURE : EXEMPLE AU FORMAT JSON
https://api.archives-ouvertes.fr/ref/structure/?q=docid:206040&wt=json&fl=*
24

25. CHAQUE RÉFÉRENTIEL A SES PROPRES CHAMPS
https://api.archives-ouvertes.fr/docs/ref/resource/journal/schema/fields/#fields
Exemple : Référentiel des revues
25

26. API Documents de HAL
https://api.archives-ouvertes.fr/docs/search
26

27. • Tous les dépôts de HAL en ligne
• +/- toutes les métadonnées d’un dépôt sous
différentes formes
• + version des métadonnées aux formats :
• Bibtex
• XML-TEI
• COinS
• Endnote
• Texte intégral indexé mais pas stocké
CONTENU API DOCUMENTS HAL
27

28. CONTENU API DOCUMENTS HAL
Exemple de métadonnées renvoyées par l’API de recherche HAL au format XML
28

29. Types de métadonnées accessibles
29
Type Usage prévu Exemple
Indexées recherche title_t
Stockées affichage label_s
Facettes listes de valeurs submitType_s
Tri tri de valeurs
multivalués
author_sort

30. API RECHERCHE – TYPES DE CHAMPS
http://api.archives-ouvertes.fr/docs/search/schema/field-types
30

31. API RECHERCHE – EXEMPLES DE CHAMPS
http://api.archives-ouvertes.fr/docs/search/schema/fields/#fields
31

32. • Point d’entrée pour les documents de HAL :
http://api.archives-ouvertes.fr/search/
API RECHERCHE - REQUÊTES
32

33. • Point d’entrée pour un portail :
http://api.archives-ouvertes.fr/search/<instance>
• Exemple :
• api.archives-ouvertes.fr/search/univ-lorraine/
• NB : Dans le cas d’un portail/instance, si un
dépôt a plusieurs versions, on ne trouve que la
dernière.
API RECHERCHE - REQUÊTES
33

34. • Point d’entrée pour une collection :
http://api.archives-ouvertes.fr/search/<TAMPON>
• Exemple :
• https://api.archives-ouvertes.fr/search/CRESSON
• NB : Dans le cas d’une collection, si un dépôt a
plusieurs versions, on ne voit que la version
tamponnée
API RECHERCHE - REQUÊTES
34

35. Nom paramètre/usage Description exemple Valeur par
défaut
q Requête de recherche q=exemple * :*
Chercher dans un champ NomDuChamp:valeur q=title_t:test
q=title_t:(printemps OR spring)
text
wt Format de réponse wt=xml Json
Equation de recherche Termes + opérateurs booléens avec des parenthèses Journal AND (Histoire OR History)
Intervalles Recherche d'intervalles submittedDateY_i:[2000 TO *]
Opérateur booléens AND OR NOT + - && || AND
fq Filtres fq=submitType_s:file
rows Nombre de résultats rows=5 30
start Décalage des résultats start=10 0
fl Champs à retourner fl=auth*,docid,label_s docid,label_s
sort Tri : nom du champ + asc ou desc sort=submittedDateY_i desc score
facet Construire des facettes facet=true false
facet.field Un champ pour faire des facettes facet.field=docType_s
facet.mincount Nombre minimum de valeurs pour retourner une facette facet.mincount=1 0
facet.sort Tri des facettes [count ou index] facet.sort=index count
PRINCIPAUX PARAMÈTRES
Valeurs + paramètres sensibles à la casse
35

36. Exemples avec l’API de recherche sur les documents de HAL
API - construire une requête
36

37. 37
API REQUÊTES / PARAMÈTRE WT = FORMAT
DE RÉPONSE (WT=FORMAT)
https://api.archives-ouvertes.fr/search/?wt=xml

38. 38
API REQUÊTES / PARAMÈTRE Q = CRITÈRE DE
RECHERCHE (Q=TERME)
https://api.archives-ouvertes.fr/search/?q=api

39. API REQUÊTES / PARAMÈTRE Q POUR
CHERCHER DANS UN CHAMP (CHAMP:VALEUR)
https://api.archives-ouvertes.fr/search/?q=title_t:api
39

40. API REQUÊTES / PARAMÈTRE FQ FILTRER
AVEC UN CHAMP (CHAMP:VALEUR)
https://api.archives-ouvertes.fr/search/?q=title_t:api&fq=submitType_s:file&wt=xml
40

41. API REQUÊTES / PARAMÈTRE FL LISTE DE
CHAMPS À RETOURNER (FL=CHAMP1,CHAMP2)
https://api.archives-ouvertes.fr/search/?wt=xml&fl=*tdate,title_s
41

42. API REQUÊTES / PARAMÈTRE SORT POUR TRIER
(SORT=CHAMP1,CHAMP2) (ASC|DESC)
/search/?wt=xml&fl=submittedDate_tdate,title_s&sort=submittedDate_tdate desc
42

43. Groupement de résultats de recherche dans des
catégories / nombre de documents
correspondant à chaque catégorie
Construire une requête -
Facettes
43

44. API REQUÊTES / FACETTES : FACET=TRUE &
FACET.FIELD=CHAMP
/search/?q=*:*&rows=0&wt=xml&facet=true&facet.field=docType_s
44

45. API REQUÊTES / FACETTES PIVOT :
FACET=TRUE & FACET.PIVOT=CHAMP1,CHAMP2
/search/?q=*:*&rows=0&wt=xml&indent=true&facet=true&facet.pivot=docType_s,submitType_s
45

46. API REQUÊTES / FACETTES PLAGE :
FACET=TRUE & FACET.RANGE=CHAMP
search/?q=*:*&rows=0&wt=xml&indent=true&facet=true&facet.range=submittedDateY_i&facet.range.start=19
90&facet.range.end=2010&facet.range.gap=2
46

47. Exemples avec l’API de recherche sur les Auteurs
API - construire une requête
47

48. AUTEURS OÙ L’ORGANISME PAYEUR EST
UNIVERSITÉ DE LORRAINE
https://api.archives-ouvertes.fr/ref/author/?q=structureId_i:413289&wt=xml&indent=true
48
&sort=lastName_s asc
&fl=*Name_s
+ tri par nom de famille +
tous les champs finissant
par Name_s

49. AUTEURS OÙ L’ORGANISME PAYEUR EST
UNIVERSITÉ DE LORRAINE + QUI ONT UN IDHAL
https://api.archives-ouvertes.fr/ref/author/?q=structureId_i:413289&wt=xml&indent=true
49
&fq=idHal_s:["" TO *]
ou l’inverse, sans IDHAL :
&fq=-idHal_s:["" TO *]

50. Exemples avec l’API de recherche sur les Structures
API - construire une requête
50

51. STRUCTURES AVEC L’UNIVERSITÉ DE LORRAINE
POUR TUTELLE
https://api.archives-ouvertes.fr/ref/structure/?q=*:*&fq=parentDocid_i:413289
51

52. STRUCTURES AVEC L’UNIVERSITÉ DE LORRAINE
POUR TUTELLE
https://api.archives-ouvertes.fr/ref/structure/?q=*:*&fq=parentDocid_i:413289
52
&group=true
&group.field=type_s
&group.limit=
+ Grouper les résultats par type de
structure
+ 2 résultats seulement par groupe

53. TYPES DE STRUCTURES AVEC L’UNIVERSITÉ DE
LORRAINE POUR TUTELLE
https://api.archives-ouvertes.fr/ref/structure/?q=*:*&fq=parentDocid_i:413289&facet=true&facet.field=type_s&r
ows=0
53

54. Exemples avec l’API de recherche sur les Revues
API - construire une requête
54

55. EXEMPLE RECHERCHE : RÉFÉRENTIEL REVUES
https://api.archives-ouvertes.fr/ref/journal/?wt=json&q=publisher_t:(Elsevier)&fq=valid_s:VALID&fq=sherpaColor_s:green&
fl=title_s,publisher_s,sherpaColor_s,valid_s&sort=title_s asc
wt=json format de retour JSON
q=publisher_t:(Elsevier)
revues dont l’éditeur est elsevier
&fq=valid_s:VALID limiter
aux revues validées
fq=sherpaColor_s:green
uniquement les couleurs “green”
dans SHERPA
&fl=title_s,publisher_s,sherpaC
olor_s,valid_s champs à afficher
dans la réponse
&sort=title_s asc trier les résultats
par titre
Revues avec le statut ‘green’ dans Sherpa où l’éditeur est Elsevier et la revue est validée dans le référentiel
55

56. Exemples en ligne de requêtes sur l’API de recherche HAL :
Base de connaissance de HAL : https://wiki.ccsd.cnrs.fr/wikis/hal/
Documentation API Recherche HAL :
https://api.archives-ouvertes.fr/docs/search
Extension Chromium/Chrome pour visualiser JSON :
- JSONViewer-for-Chrome :
https://github.com/teocci/JSONViewer-for-Chrome
Extension Firefox pour visualiser JSON :
- JSON-formatter
https://addons.mozilla.org/fr/firefox/addon/json-formatter
56