API HAL API de recherche HAL

Point d'entrée de l'API de recherche HAL

Par défaut le point d'entrée de l'API est http://api.documentation-administrative.gouv.fr/search/, donc le portail HAL

Limiter la recherche à un portail

Si vous le souhaitez, vous pouvez limiter vos requêtes à un portail, en précisant l'instance du portail dans l'URL

La liste des instances de portails est disponible dans le référentiel instance des Instances de portail.

Limiter la recherche à une collection

Vous pouvez aussi limiter la recherche à une collection en précisant le code de la collection dans l'URL d'accès

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.

Recherche basique

Recherche dans un champ en particulier

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

Recherche dans un champ en particulier plusieurs termes

Utiliser (terme1 terme2)

Recherche dans un champ en particulier un terme ou un autre

Utiliser (terme1 OR terme2)

Voir aussi la liste des opérateurs booléens

Recherche de phrase

Utiliser les guillemets doubles"terme1 terme2"

Troncature sur un caractère avec ?

Troncature sur plus d'un caractère avec *

Recherche approchante ~

Recherche par proximité

Opérateurs

Formats de réponse

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 :

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*

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.

Filtrer sur un intervalle de données

Il est possible de faire des requêtes sur des intervalles avec cette syntaxe champ:[valeurDébut TO valeurFin]

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.

Pagination

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

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= 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.

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

Facettes commençant par un terme

Vous pouvez limiter les facettes retournées à celles qui commencent par une chaine avec le paramètre : facet.prefix

Facettes contenant un terme

Vous pouvez limiter les facettes retournées à celles contenant une chaine avec le paramètre : facet.contains

Pour ignorer la casse

En plus de facet.contains ajouter le paramètre : facet.contains.ignoreCase=true pour ignorer la casse

Facettes avec pivots

Les champs qui ne sont pas multivalués peuvent permettre de faire un pivot sur une facette. Par exemple une liste de types de documents, avec pour chaque type une liste de type de dépôts associée facet.pivot=docType_s,submitType_s

Facettes avec une plage de données

Il est possible d'obtenir des facettes avec des plages de valeurs

            
<response>
<result name="response" numFound="953150" start="0"></result>
<lst name="facet_ranges">
<lst name="submittedDateY_i">
<lst name="counts">
<int name="1990">3296</int>
<int name="1992">3439</int>
<int name="1994">4187</int>
<int name="1996">3742</int>
<int name="1998">6641</int>
<int name="2000">14433</int>
<int name="2002">6527</int>
<int name="2004">27913</int>
<int name="2006">136634</int>
<int name="2008">167039</int>
</lst>
<int name="gap">2</int>
<int name="start">1990</int>
<int name="end">2010</int>
</lst>
</lst>
</lst>
</response>
        

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