Avec cette API vous pouvez utiliser la syntaxe de Apache Solr. En plus des options détaillées ci-dessous vous pouvez consulter la documentation en anglais de Apache Solr

Requêtes

Il faut au moins un paramètre dans l'URL pour faire une requête, ce paramètre est q

Ce paramètre contient la requête à effectuer.

Le paramètre doit être suivi du nom du champ dans lequel rechercher puis de la valeur à chercher.

Un certain nombre de caractères utilisés par la syntaxe de Apache Solr doivent être échappés avant d'être envoyés à l'API. Voir RFC3986

Caractères utilisés par Apache Solr à échapper + - && || ! ( ) { } [ ] ^ " ~ * ? : \.

Vous pouvez échapper ces caractères avec un \ avant le caractère. Par exemple (1+1):2 devient \(1\+1\)\:2.

Exemples
q=exemple

Exemple recherche du terme 'test' :

http://api.archives-ouvertes.fr/search/?q=test&wt=xml

Recherche basique

Exemples

Si le nom du champ dans lequel chercher est omis, par défaut la recherche porte sur l'index text qui contient les valeurs de plusieurs champs.

Ainsi :

http://api.archives-ouvertes.fr/ref/anrproject/?q=asie&wt=xml

donne le même résultat que :

http://api.archives-ouvertes.fr/ref/anrproject/?q=text:asie&wt=xml

Recherche dans un champ en particulier

Pour chercher dans un champ particulier la syntaxe est champ:terme

Exemple

Recherche du terme 'japon' dans le champ title_t

http://api.archives-ouvertes.fr/search/?q=title_t:japon&wt=xml

Recherche dans un champ en particulier plusieurs termes

L'opérateur booléen par défaut est AND

Utiliser (terme1 terme2)

Exemple

Recherche des termes 'japon' et 'france' dans le champ title_t

http://api.archives-ouvertes.fr/search/?q=title_t:(japon france)&wt=xml

Recherche dans un champ en particulier un terme ou un autre

Utiliser (terme1 OR terme2)

Voir aussi la liste des opérateurs booléens

Exemple

Recherche des termes 'japon' ou 'france' dans le champ title_t

http://api.archives-ouvertes.fr/ref/europeanproject/?q=title_t:(japon OR france)&wt=xml

Recherche de phrase

Utiliser les guillemets doubles"terme1 terme2"

Exemple

Recherche de la phrase 'Dictionnaire des idées reçues' dans le champ title_t

http://api.archives-ouvertes.fr/search/?q=title_t:"Dictionnaire des idées reçues"&wt=xml

Troncature sur un caractère avec ?

Troncature sur plus d'un caractère avec *

Recherche approchante ~

Exemple

La syntaxe aluminum~ retourne des titres qui contiennent aluminum, Aluminium, alumimium, etc.

On peut préciser le nombre de permutations possibles avec un chiffre entre 0 et 2 (par défaut) : aluminum~1 api.archives-ouvertes.fr/search/?q=title_t:aluminum~&wt=xml&fl=title_s

Recherche par proximité

Exemple

La syntaxe "aluminium fer"~3 cherche des titres qui contiennent aluminium et fer à une distance maximale de 3 termes : api.archives-ouvertes.fr/search/?q=title_t:"aluminium fer"~3&wt=xml&fl=title_s


Opérateurs

Opérateur booléen Symbole Description
AND && Les termes de chaque côté de l'opérateur doivent être présents
NOT ! Le terme suivant l'opérateur doit être absent
OR || Au moins un des 2 termes de chaque côté de l'opérateur doit être présent
  + Le terme suivant l'opérateur doit être présent
  - Le terme suivant l'opérateur doit être absent
Exemples
  • Paris -France +Texas
  • Paris AND France AND history NOT (Texas AND history)
  • Journal AND (Histoire OR History)

Formats de réponse

Le format de réponse par défaut est JSON

Le format de réponse est spécifié par le paramètre wt

Par exemple wt=json

Les réponses peuvent être obtenues dans plusieurs formats :

Format Paramètre Description
JSON (format par défaut) json Réponse de Apache Solr au format JSON
XML xml Réponse de Apache Solr au format XML
CSV csv Réponse de Apache Solr au format CSV
(séparateur de champs , - valeurs séparées par ")
Ajouter indent=true pour indenter le format de réponse.

Champs retournés dans la réponse

Par défaut seuls les champs docid et label_s sont retournés dans une réponse. Cependant tous les champs stockés peuvent être retournés dans le format de réponse.

Le paramètre pour choisir les champs à retourner est fl .

Les champs demandés doivent être séparés par le signe ,

On peut utiliser le caractère * comme troncature de nom de champ, eg fl=cha*

Exemple
fl=champ1_s,champ2_bool,champ3_t

Exemple pour ne retourner que le champ label_s :

http://api.archives-ouvertes.fr/ref/europeanproject/?q=*:*&wt=xml&fl=label_s

Tri des résultats

Par défaut, les résultats sont triés par pertinence. Le tri des résultats peut se faire sur n'importe quel champ en évitant les champs de type text (suffixe "_t") et les champs multi-valués qui donneront des résultats imprévisibles.

Le paramètre pour choisir les champs à retourner est sort + le sens de tri asc ou desc .


Filtres sur les requêtes

Pour limiter les résultats retournés, il est possibles d'utiliser des filtres

Le paramètre pour ajouter des filtres est fq suivi de la requête servant au filtre.

Exemple
fq=sherpaColor_s:green

Exemple avec le référentiel des revues :

http://api.archives-ouvertes.fr/ref/journal/?q=studies&wt=xml&fl=*&fq=sherpaColor_s:green

Nombre de résultats

Le nombre de réponses à retourner est définit par le paramètre rows .

Le nombre total de dépôt/notices ne change pas avec ce paramètres, seul le nombre de résultats effectivement retournés varie.

Par défaut les requêtes ne retournent que les 30 premiers résultats, le maximum autorisé est 10000.
Si vous souhaitez plus de résultats vous devez utiliser la pagination.

Le paramètre &rows=0 peut permettre de ne retourner que le nombre de résultats et d'enlever les documents du corps de la réponse. Vous pouvez par exemple utiliser ce paramètre à des fins de statistiques ou si vous voulez retourner uniquement des facettes.

En dehors de besoins spécifiques, il vaut mieux éviter de dépasser les 500/1000 lignes par réponse - pour des raisons de performance.

Pagination

Les résultats peuvent être paginés/décalés avec le paramètre start .

Exemple

Pour décaler les résultats et commencer au résultat 50 :

http://api.archives-ouvertes.fr/ref/europeanproject/?q=*:*&start=50&rows=50

Curseurs

Si vous devez parcourir plusieurs milliers de résultats, pour des raisons de performance il est fortement recommandé d'utiliser les curseurs

Utilisation :

Spécifier le nombre de résultats à retourner avec le paramètre &rows=

Ajouter un tri par clé unique à la requête, dans nos référentiels la clé unique est docid . Donc ajouter &sort=docid asc à votre requête.

À votre première requête, ajouter le paramètre &cursorMark=* pour demander à solr d'ajouter un curseur dans le résultat de votre requête.

Le résultat de la requête contiendra par exemple "nextCursorMark":"AoFakgE="

Pour la requête suivante, ajouter &cursorMark=AoFakgE=AoFakgE= est la valeur récupérée dans le résultat de la requête précédente.

Continuer ainsi en récupérant chaque paramètre cursorMark de la requête précédente.

Fin des résultats :

Quand la valeur de cursorMark dans le résultat est la même que celle envoyée avec la requête il n'y a plus de résultats à récupérer.

Plus d'information dans le guide de référence de Solr


Utilisation des facettes

Les facettes sont des listes de termes extraits en fonction d'une requête.

On peut les utiliser pour avoir une liste de valeurs distinctes sur un champ donné.

Pour générer des facettes, il faut ajouter le paramètre facet=true à une requête.

Il faut ensuite ajouter les champs avec lesquel construire les facettes avec le paramètre facet.field=NomDuChamp à une requête.

Plus d'information dans la documentation sur les facettes de Apache Solr

Exemples
facet=true&facet.field=type_s

Exemple pour avoir une d'acronymes de projets européens :

http://api.archives-ouvertes.fr/ref/europeanproject/?q=*%3A*&rows=0&wt=json&indent=true&facet=true&facet.field=acronym_s

Ajouter le paramètre facet.sort=index pour un tri lexicographique :

http://api.archives-ouvertes.fr/ref/europeanproject/?q=*%3A*&rows=0&wt=json&indent=true&facet=true&facet.field=acronym_s&facet.sort=index

Ajouter le paramètre facet.sort=count pour trier par nombre d'occurences :

http://api.archives-ouvertes.fr/ref/europeanproject/?q=*%3A*&rows=0&wt=json&indent=true&facet=true&facet.field=acronym_s&facet.sort=count

Ajouter le paramètre facet.prefix= pour retourner des facettes qui commencent par un préfixe :

http://api.archives-ouvertes.fr/ref/europeanproject/?q=*%3A*&rows=0&wt=json&indent=true&facet=true&facet.field=acronym_s&facet.prefix=B

Liste d'acronymes de projets européens avec l'appel à projet FP7-PEOPLE-2010-IEF triée par nombre d'occurences :

http://api.archives-ouvertes.fr/ref/europeanproject/?q=callId_s:"FP7-PEOPLE-2010-IEF"&rows=0&wt=json&indent=true&facet=true&facet.field=acronym_s

On peut demander plusieurs facettes dans la même requête :

http://api.archives-ouvertes.fr/ref/europeanproject/?q=*:*&rows=0&wt=xml&indent=true&facet=true&facet.field=callId_s&facet.field=acronym_s&facet.limit=5

Les champs qui ne sont pas multivalués peuvent permettre de faire un pivot sur une facette. Par exemple une liste d'appels à projets, avec pour chaque appel une liste d'acronymesfacet.pivot=callId_s,acronym_s

http://api.archives-ouvertes.fr/ref/europeanproject/?q=*:*&rows=0&wt=xml&indent=true&facet=true&facet.pivot=callId_s,acronym_s&facet.limit=3

Grouper des résultats

Vous pouvez obtenir vos résultats de requêtes groupés selon un critère de votre choix, à condition que le critère soit représenté par un champ non multivalué et de type string

Paramètre Type Description
group Booléen Si true les résultats seront groupés
group.field chaine Le champ doit être de type string et ne doit pas être multivalué
group.limit entier Le nombre de résultats dans chaque groupe (1 par défaut).
group.sort Tri Le critère de tri à l'intérieur des groupes, par défaut score desc
group.query requête Requête permettant de retourner un groupe de documents, répétable
Exemples

Les 20 premiers documents de la collection FRANCE-GRILLES, triés par date de publication descendante, groupés par type de dépôt :

http://api.archives-ouvertes.fr/search/?q=*:*&fq=collCode_s:FRANCE-GRILLES&group=true&group.field=submitType_s&indent=true&group.limit=20&wt=xml&sort=producedDate_tdate desc

Les 20 premiers documents de la collection FRANCE-GRILLES, triés par date de publication descendante, groupés par type de documents :

http://api.archives-ouvertes.fr/search/?q=*:*&fq=collCode_s:FRANCE-GRILLES&group=true&group.field=docType_s&indent=true&group.limit=20&wt=xml&sort=producedDate_tdate desc