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.
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.
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
Pour chercher dans un champ particulier la syntaxe est champ:terme
Recherche du terme 'japon' dans le champ title_t
http://api.archives-ouvertes.fr/search/?q=title_t:japon&wt=xml
AND
Utiliser (terme1 terme2)
Recherche des termes 'japon' et 'france' dans le champ title_t
http://api.archives-ouvertes.fr/search/?q=title_t:(japon france)&wt=xml
Utiliser (terme1 OR terme2)
Voir aussi la liste des opérateurs booléens
Recherche des termes 'japon' ou 'france' dans le champ title_t
http://api.archives-ouvertes.fr/ref/anrproject/?q=title_t:(japon OR france)&wt=xml
Utiliser les guillemets doubles"terme1 terme2"
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
?*~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
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é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 |
Paris -France +TexasParis AND France AND history NOT (Texas AND history)Journal AND (Histoire OR History)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
")
|
indent=true
pour indenter le format de 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*
fl est disponible avec les formats de sortie :
fl=champ1_s,champ2_bool,champ3_t
Exemple pour ne retourner que le champ label_s :
http://api.archives-ouvertes.fr/ref/anrproject/?q=*:*&wt=xml&fl=label_s
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
.
sort=champ_s asc
Exemple
http://api.archives-ouvertes.fr/ref/anrproject/?q=*:*&wt=xml&sort=docid asc
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.
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
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.
Récupérer 100 résultats :
http://api.archives-ouvertes.fr/ref/anrproject/?q=*:*&rows=100
Les résultats peuvent être paginés/décalés avec le paramètre
start
.
Pour décaler les résultats et commencer au résultat 50 :
http://api.archives-ouvertes.fr/ref/anrproject/?q=*:*&start=50&rows=50
Si vous devez parcourir plusieurs milliers de résultats, pour des raisons de performance il est fortement recommandé d'utiliser les curseurs
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=
où
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.
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
Obtenir un premier cursorMark :
http://api.archives-ouvertes.fr/ref/anrproject/?q=*:*&rows=10&sort=docid asc&cursorMark=*
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
facet=true&facet.field=type_s
Exemple pour avoir une liste d'années de projets ANR :
http://api.archives-ouvertes.fr/ref/anrproject/?q=*%3A*&rows=0&wt=json&indent=true&facet=true&facet.field=yearDate_s
Ajouter le paramètre facet.sort=index pour un tri lexicographique :
http://api.archives-ouvertes.fr/ref/anrproject/?q=*%3A*&rows=0&wt=json&indent=true&facet=true&facet.field=yearDate_s&facet.sort=index
Ajouter le paramètre facet.sort=count pour trier par nombre d'occurences :
http://api.archives-ouvertes.fr/ref/anrproject/?q=*%3A*&rows=0&wt=json&indent=true&facet=true&facet.field=yearDate_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/anrproject/?q=*%3A*&rows=0&wt=json&indent=true&facet=true&facet.field=acronym_s&facet.prefix=B
Liste d'acronymes de projets ANR en 2006 triée par nombre d'occurences :
http://api.archives-ouvertes.fr/ref/anrproject/?q=yearDate_s:2006&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/anrproject/?q=*:*&rows=0&wt=xml&indent=true&facet=true&facet.field=yearDate_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'années, avec pour chaque année une liste d'acronymesfacet.pivot=yearDate_s,acronym_s
http://api.archives-ouvertes.fr/ref/anrproject/?q=*:*&rows=0&wt=xml&indent=true&facet=true&facet.pivot=yearDate_s,acronym_s&facet.limit=3
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 |
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