Résultats de recherche

/api/search.json effectue la même recherche que la page de recherche (voir Zoeken) et affiche le résultat en une seule réponse, plutôt que de l'afficher au fur et à mesure de la recherche. Cette adresse peut être consultée sans compte et sans clé.

Paramètres

• q : le terme de recherche. Obligatoire ; s'il manque, l'adresse renvoie un statut 400 ;

• mode : l'une des quatre valeurs. En son absence, on a all :

  • all : chaque mot apparaît dans le même texte (le texte de référence) ;
  • any : au moins l'un des mots est présent ;
  • near : chaque mot se trouve à moins de dix mots de l’autre ;
  • exact : les mots sont écrits sans espace et dans cet ordre précis.

  Pour savoir ce que signifient les quatre autres éléments et comment traiter une source ne comportant ni « ou » ni « proximité », consultez Zoeken ;

• page_size : 100, 500, 1000 ou max (la valeur maximale définie par la source). En l'absence de cette valeur, la valeur par défaut définie sur cette installation s'applique, à savoir 100, sauf si l'administrateur a modifié la valeur BesluitBron:Search:PageSize ;

• date_from, date_to : les limites du filtre de date, sous la forme jjjj-mm-dd. Une limite vide laisse cette option ouverte ;

• date_undated : 1 pour afficher un résultat sans date tant que le filtre de date est activé, c'est-à-dire tant que date_from ou date_to est défini. En l'absence de l'une ou l'autre de ces limites, ce paramètre n'a aucun effet : dans ce cas, le filtre n'est pas activé et tous les résultats sont pris en compte, avec ou sans date. Le fonctionnement est décrit dans Zoeken, sous « Filtrer par date » ;

• culture : la langue du résultat, de la remarque et de la méthode par source, par exemple de. En l'absence de ce paramètre, la langue est déterminée par le cookie de langue du demandeur ; sinon, c'est Accept-Language.

Une valeur non valide est une erreur, et non un retour par défaut implicite

Depuis la version 1.3.86, l'adresse renvoie un statut 400 dès que mode, page_size, date_from ou date_to contient une valeur qui ne figure pas dans la liste ci-dessus, avec un champ « error » indiquant de quel paramètre il s'agissait et un champ « error_description » précisant les valeurs autorisées. Par exemple, mode=xxx ou page_size=250 affichent ainsi tous deux une erreur claire au lieu de basculer silencieusement vers la valeur par défaut. Ce n’est pas le cas de la page de recherche elle-même : là, une valeur non valide saisie dans la barre d’adresse revient à la valeur par défaut, car un visiteur lit rarement avec précision ce qu’il a tapé dans la barre d’adresse et un message d’erreur n’apporte aucune solution. Un programme qui appelle cette adresse peut quant à lui corriger sa propre erreur ; il voit donc s’afficher le message d’erreur au lieu d’une supposition corrigée en silence quant à ce qu’il voulait dire.

Ce que renvoie l'adresse

Une seule réponse indiquant le terme de recherche, les mots isolés, la méthode choisie, la durée et, pour chaque source, le résultat, le nombre de résultats, le total indiqué par la source elle-même et si ce total correspond à un décompte ou à une estimation. Les sources sont classées par ordre alphabétique, et non dans l'ordre dans lequel elles ont répondu : cette adresse renvoie les résultats de la recherche dès qu'elle est prête, il n'y a donc pas d'ordre d'arrivée à conserver.

Chaque source fournit au maximum le nombre demandé par page_size, soit la même limite que celle appliquée par la page elle-même. Si page_size demande plus que ce que la source peut fournir en une seule requête, cette adresse récupère elle-même plusieurs pages auprès de cette source, jusqu’à ce que le nombre demandé soit atteint ou que la source soit épuisée, à partir de la version 1.3.86.

Une source peut avoir sa propre limite stricte qu’aucun page_size ne peut dépasser : OpenTK, par exemple, ne renvoie jamais plus de deux cent quatre-vingts résultats pour une seule requête. Si tel est le cas, la réponse indique « at_absolute_ceiling: true » pour cette source, à partir de la version 1.3.86 : aucune valeur supérieure à page_size n'est possible et aucune requête supplémentaire ne permettra d'obtenir davantage de résultats.

Le budget partagé

Cette adresse partage avec la page de recherche le budget correspondant à une requête par seconde, car toutes deux interrogent les mêmes plateformes sources. Lorsque ce budget est épuisé, l'adresse renvoie un code d'état 429 et un champ « Retry-After» indiquant le nombre de secondes à patienter.

Ce qui est consigné

Un accès à cette adresse est enregistré de la même manière qu'une recherche à l'écran : une ligne par source dans le journal des accès, sous la catégorie « SEARCH ». Voir Privacy en Cookies.