Voir la source de API:Recherche:Hal

Requêtes effectuées par le CCSD lors d'une journée de formation du CCSD le 17 mars 2016 (Importer dans HAL avec Bib2Hal (format BibTeX) et utiliser les API de recherche HAL)

== API de recherche HAL ==

=== Exemple 1 - Varia ===
Pour le portail ENS-LYON 
 https://api.archives-ouvertes.fr/search/ens-lyon/ 
Liste 20 publications
 https://api.archives-ouvertes.fr/search/ens-lyon/?q=*:*&rows=20
Triées par date de production + récentes en premier
 [https://api.archives-ouvertes.fr/search/ens-lyon/?q=*:*&rows=20&sort=producedDate_tdate%20desc https://api.archives-ouvertes.fr/search/ens-lyon/?q=*:*&rows=20&sort=producedDate_tdate desc]

Toujours dans le portail ENS-LYON, on ajoute un filtre pour limiter les publis à celles du labo dont l'acronyme est IGFL
 https://api.archives-ouvertes.fr/search/ens-lyon/?q=*:*&row=20&sort=producedDate_tdate%20desc&fl=halId_s,producedDate_tdate,label_s,structAcronym_s&fq=structAcronym_s:IGFL

on peut aussi utiliser son [https://aurehal.archives-ouvertes.fr/structure/read/id/39280 identifiant de structure] 39280 :
 https://api.archives-ouvertes.fr/search/ens-lyon/?q=*:*&row=20&sort=producedDate_tdate%20desc&fl=halId_s,producedDate_tdate,label_s,structAcronym_s&fq=structId_i:39280

Si l'on veut limiter le corpus à certains types de documents, les types peuvent être obtenus dans le référentiel dédié : 
 https://api.archives-ouvertes.fr/ref/doctype
ou par cette requête qui donne en plus le nombre de docs pour chaque type, ici uniquement dans le portail ens-lyon : 
 https://api.archives-ouvertes.fr/search/ens-lyon/?q=*:*&rows=0&facet=true&facet.field=docType_s

En ayant repéré les types de documents souhaités, on connaît les filtres à ajouter par exemple pour avoir uniquement les monographies + articles :
 https://api.archives-ouvertes.fr/search/ens-lyon/?q=*:*&rows=20&sort=producedDate_tdate%20desc&fq=docType_s:(ART%20OR%20OUV%20OR%20COUV%20OR%20DOUV)

=== Exemple 2 - Liste d'auteurs affiliés à une structure ===
Obtenir une liste d'auteurs affiliés à la structure [https://aurehal.archives-ouvertes.fr/structure/read/id/148117 AgroParisTech] avec le nombre de dépôts par auteur

on utilise le champ structHasAuthId_fs qui a ce type de contenu : 
 148117_FacetSep_AgroParisTech_JoinSep_1048930_FacetSep_Daniel Sauvant
Identifiant de structure + _FacetSep_ + Nom structure + _JoinSep_ + Identifiant Auteur + _FacetSep_ + Nom auteur

on demande une facette sur ce champ :

 https://api.archives-ouvertes.fr/search/?q=*%3A*&rows=0&&facet=true&facet.field=structHasAuthId_fs

on restreint la liste des facettes à celles qui commencent par l'identifiant  de la structure qui nous intéresse (plus le séparateur _FacetSep_) :
 https://api.archives-ouvertes.fr/search/?q=*%3A*&rows=0&&facet=true&facet.field=structHasAuthId_fs&facet.prefix=148117_FacetSep_

si la liste est trop courte on peut l'allonger par exemple à 3000 (facet.limit=3000) :
 https://api.archives-ouvertes.fr/search/?q=*%3A*&rows=0&&facet=true&facet.field=structHasAuthId_fs&facet.prefix=148117_FacetSep_&facet.limit=3000



=== Exemple 3 - Auteurs des articles d'une collection ===
Une requête sur les déposants de ma collection qui affiche : nom du déposant/sigle ou nom du labo
 https://api.archives-ouvertes.fr/search/UNIV-AMU/?q=*:*&facet=true&facet.field=authIdHasPrimaryStructure_fs&rows=0&wt=xml

Même chose mais répartie par type de dépôt :
  https://api.archives-ouvertes.fr/search/?q=*:*&facet=true&facet.pivot=submitType_s,authIdHasPrimaryStructure_fs&rows=0&wt=json


NB : ce ne sont pas forcément les déposants, mais plutôt les auteurs et leurs co-auteurs mais si on veut que les dépôts en auto-archivage on peut ajouter le filtre ''selfArchiving_bool:true'' : 
 https://api.archives-ouvertes.fr/search/UNIV-AMU/?q=*:*&facet=true&facet.field=authIdHasPrimaryStructure_fs&rows=0&wt=xml&fq=selfArchiving_bool:true

=== Exemple 4 - Nombre de dépôts par type de dépôt ===
Pour la collection IRDEP : Nombre de dépôts par type de dépôt 
 https://api.archives-ouvertes.fr/search/IRDEP/?q=*:*&facet=true&facet.field=submitType_s&rows=0&wt=xml

Dans HAL  : Nombre de dépôts par type de dépôt 
 https://api.archives-ouvertes.fr/search/?q=*:*&facet=true&facet.field=submitType_s&rows=0&wt=xml

Dans le portail HAL-AMU  : Nombre de dépôts par type de dépôt 
 https://api.archives-ouvertes.fr/search/amu/?q=*:*&facet=true&facet.field=submitType_s&rows=0&wt=xml

Dans HAL : Nombre de dépôts par type de dépôt où la structure d'un des auteurs a pour parent Aix-Marseille Université [AMU] 198056
 https://api.archives-ouvertes.fr/search/?q=*:*&fq=structIsParentOf_fs:198056_*&rows=0&facet=true&facet.field=docType_s&wt=xml

=== Exemple 5 - Nombre de dépôts par année, type de dépôt et type de document ===
Le nombre de dépôts, par année, par type de dépôt et par type de document avec facet.pivot
 https://api.archives-ouvertes.fr/search/?q=*:*&wt=xml&rows=0&facet=true&facet.pivot=submittedDateY_i,submitType_s,docType_s


=== Exemple 6 - Dépôts dans une collection mais pas dans une autre ===

Les dépôts qui ne sont pas dans la collection DICE mais qui sont dans la collection CERIC. Autrement dit : la collection DICE récupère-t-elle bien les dépôts de DICE/CERIC ?
 [https://api.archives-ouvertes.fr/search/CERIC/?q=*:*&wt=xml&fq=collCode_s:(NOT%20DICE) https://api.archives-ouvertes.fr/search/CERIC/?q=*:*&wt=xml&fq=collCode_s:(NOT DICE)]


=== Exemple 7- Chercheurs ayant créé leur IdHAL pour une structure ===
Lister des chercheurs ayant créé leur IdHal pour une structure par exemple (Maison des Sciences de l'Homme de Dijon docid=226306)

La liste comprend des chercheurs avec et sans idhal. Pour ceux qui ont un idhal la chaine le représentant est entre ''_JoinSep_'' et ''_FacetSep_'' 

* Exemple avec Idhal : 226306_FacetSep_Maison des Sciences de l'Homme de Dijon''_JoinSep_'''''lsaligny'''''_FacetSep_''Saligny Laure
* Exemple sans Idhal : 226306_FacetSep_Maison des Sciences de l'Homme de Dijon''_JoinSep__FacetSep_''Alazard Céline


 https://api.archives-ouvertes.fr/search/?q=*:*&rows=0&facet=true&facet.field=structHasAuthIdHal_fs&facet.prefix=226306_&wt=xml&facet.limit=10000 

Même chose dans le portail univ-bourgogne
 https://api.archives-ouvertes.fr/search/?q=*:*&rows=0&facet=true&facet.field=structHasAuthIdHal_fs&facet.prefix=300270_&wt=xml&facet.limit=10000 

Même chose dans la collection CRC
 https://api.archives-ouvertes.fr/search/?q=*:*&rows=0&facet=true&facet.field=structHasAuthIdHal_fs&facet.prefix=390620_&wt=xml&facet.limit=10000 

Même chose pour le labo IREDU  (structId_i:245758)
 https://api.archives-ouvertes.fr/search/?q=*:*&rows=0&facet=true&facet.field=structHasAuthIdHal_fs&facet.prefix=245758_&wt=xml&fq=structId_i:245758&facet.limit=10000

=== Exemple 8 - Liste de documents par type de dépôt ===
Une liste de documents groupée par type de dépôt, 20 publications par type de dépôt
 [http://api.archives-ouvertes.fr/search/?q=*:*&group=true&group.field=submitType_s&indent=true&group.limit=20&wt=xml&group.sort=producedDate_tdate%20desc http://api.archives-ouvertes.fr/search/?q=*:*&group=true&group.field=submitType_s&indent=true&group.limit=20&wt=xml&group.sort=producedDate_tdate desc]

=== Exemple 9 - Liste des revues où les déposants publient ===
Pour le portail Lille 3 liste des revues où les déposants publient
 https://api.archives-ouvertes.fr/search/univ-lille3/?indent=true&rows=0&facet=true&facet.field=journalTitle_s&wt=xml

=== Exemple 10 - Nombre de dépôts par contributeur ===
Pour le portail Lille 3, par année de dépôt, nombre de dépôts par contributeur
 https://api.archives-ouvertes.fr/search/univ-lille3/?q=*:*&facet=true&facet.pivot=submittedDateY_i,contributorFullName_s&rows=0&wt=xml&facet.limit=100

=== Exemple 11 - Flux RSS des derniers dépôts d'une collection ===
Flux RSS des derniers dépôts de la collection LIGM :
 https://api.archives-ouvertes.fr/search/?wt=rss&q=collCode_s%3A%28LIGM%29&sort=submittedDate_tdate+desc&rows=50

=== Exemple 12 - Liste de références d'un laboratoire dans HAL ===
Pour le "Laboratoire Identité Culturelle, Textes et Théâtralité" :
  https://api.archives-ouvertes.fr/search/?q=structId_i:109351&wt=xml&rows=1000
Afin d'obtenir la liste sous format csv (tableur) :
 https://api.archives-ouvertes.fr/search/?q=structId_i:109351&wt=csv&rows=1000

=== Exemple 13 - Nombre de dépôts de thèses ===
* total par année :
  https://api.archives-ouvertes.fr/search/?q=*:*&fq=docType_s:THESE&rows=0&wt=json&indent=true&facet=true&facet.field=submittedDateY_i
* total par domaine de recherche :
  https://api.archives-ouvertes.fr/search/?q=*:*&fq=docType_s:THESE&rows=0&wt=json&indent=true&facet=true&facet.field=domainAllCode_s
* total par année en sociologie : 
  https://api.archives-ouvertes.fr/search/?q=*:*&fq=docType_s:THESE%20AND%20domainAllCode_s:shs.socio&rows=0&wt=json&indent=true&facet=true&facet.field=submittedDateY_i

=== Exemple 14 - Nombre de dépôts dans HAL ===
* total par année (notices et documents) :
  https://api.archives-ouvertes.fr/search/?q=*:*&rows=0&wt=json&indent=true&facet=true&facet.field=submittedDateY_i&facet.sort=count
* total par année (documents uniquement) :
  https://api.archives-ouvertes.fr/search/?q=fileType_s:%22file%22&rows=0&wt=json&indent=true&facet=true&facet.field=submittedDateY_i&facet.sort=count
* total en SHS par année (notices et documents) : 
  https://api.archives-ouvertes.fr/search/?q=*:*&fq=domain_s:%220.shs%22&rows=0&wt=json&indent=true&facet=true&facet.field=submittedDateY_i&facet.sort=count
* total en SHS par année (documents uniquement) :
  https://api.archives-ouvertes.fr/search/?q=fileType_s:%22file%22&fq=domain_s:%220.shs%22&rows=0&wt=json&indent=true&facet=true&facet.field=submittedDateY_i&facet.sort=count

=== Exemples sur d'autres sites ===

  * sur Bibliopedia : http://bibliopedia.fr/wiki/AdminHAL
  * avec les réponses cachées, pour s'entraîner : [https://hal-upec-upem.archives-ouvertes.fr/page/api https://hal-upec-upem.archives-ouvertes.fr/page/api]

=== Fonctionnement des dates renvoyées par l'API ===
==== submittedDate versus releasedDate ====
- releasedDate contient la date de mise en ligne du ou des fichier(s) (c.à.d. lorsque l'étape de validation est terminée, i.e. date de fin du processus de modération), OU, à défaut, la date de dépôt (date de création) de la notice bibliographique.

- En principe, submittedDate contient la date d'ajout du fichier (lorsque celui-ci a été rajouté a posteriori sur une notice bibliographique), OU, à défaut, la date de création du dépôt. 

Mais il arrive parfois que la submittedDate soit postérieure (de plusieurs jours) à la releasedDate : cf. par exemple [https://halshs.archives-ouvertes.fr/halshs-00867376 halshs-00867376] et [https://halshs.archives-ouvertes.fr/halshs-00867379 halshs-00867379]. On constate alors dans l'historique qu'il y a eu une "mise en ligne" à une date postérieure à la date de fin de modération. 

Pour avoir la vraie date de création d'un dépôt, il convient donc de faire : 

<code>date_de_creation := Min(submittedDate, releasedDate)</code>

==== producedDate ====
Lorsque le champ "date de publication" contient la valeur "0" (zéro), l'API ne retourne PAS la valeur zéro dans le champ producedDate. Le fonctionnement observé est en réalité un peu plus compliqué, à savoir :

<code>
SI date_de_publication (dans HAL) <big>≠</big> 0 ALORS
  SI conferenceStartDate_tdate EST renseigné ALORS
    producedDate_tdate := conferenceStartDate_tdate
    // en pareille circonstance, il est '''impossible''' de récupérer la date de publication (des actes du colloque) via l'API.
  SINON
    SI defenseDate_tdate EST renseigné ALORS
       producedDate_tdate := defenseDate_tdate
    SINON
      producedDate_tdate := date_de_publication
    FIN DE SI
  FIN DE SI
SINON
  SI writingDate_tdate EST renseigné ALORS
    producedDate_tdate := DATE_DE(writingDate_tdate)
  SINON
    producedDate_tdate := DATE_DE(submittedDate_tdate)
  FIN DE SI
FIN DE SI
</code>

Dans le pseudo-code ci-dessus, la fonction DATE_DE(...) a pour effet de ne prendre que la date en elle-même (c.a.d. ne conserve pas l'heure, qui se trouve après "T").
Exemple : DATE_DE("2016-09-24T20:48:30Z") donne comme résultat : "2016-09-24T00:00:00Z".

Par conséquent, si vous voulez repérer, dans les résultats retournés par l'API, les dépôts qui ont pour date de publication la valeur "0" (qui sont généralement des publications "à paraître" ou "sous presse"), il vous faut utiliser l'astuce suivante : 

<code>boolean a_pour_date_de_publication_zero := (producedDate_tdate == DATE_DE(submittedDate_tdate))  OU  (producedDate_tdate == DATE_DE(writingDate_tdate))</code>

Attention de bien utiliser ici les champs ..._tdate et non pas les champs ..._s ni le triplet ...Y_i  / ...M_i  / ...D_i car il arrive parfois que producedDate_tdate contienne une date précise (ex. "2015-01-01T00:00:00Z") là où les autres champs producedDate_* ne contiennent que l'année. Pour des questions de fiabilité du résultat, il est important en effet que ces comparaisons ne soient pas effectuées seulement sur l'année, mais bien sur le jour/mois/année.

Cette méthode n'est toutefois pas fiable à 100 % :
* c'est très peu probable, mais il se pourrait que quelqu'un fasse un dépôt dans HAL exactement le jour même de la publication - ET - qui soit suffisamment zêlé pour saisir dans ce dépôt la date de publication exacte, au jour près (bien que la plupart du temps, les gens ne mettent que l'année de publication, et que, la plupart du temps aussi, ils ne déposent pas dans HAL pile poil le jour même de la publication)
* elle ne fonctionne pas pour les communications à un congrès avec actes (pour lesquels l'API de HAL ne nous permet tout simplement PAS de récupérer la date de publication des actes !)
* si jamais quelqu'un a renseigné dans les champs "Date de production/écriture" et "Date de publication" la même date, on se retrouve avec des faux positifs... Inversement, si on enlève la deuxième moitié de la comparaison ci-dessus, on passe sous silence tous les dépôts qui ont date de publication à zéro ET date de production non vide.

Cette solution n'est donc pas parfaite, mais puisque l'API ne nous retourne pas "0" lorsque le champ "date de publication" contient pourtant bien "0" en base de données, il n'y a guère d'autre façon de faire...