En bref. Le paramètre offset de Brave compte les pages de résultats de la taille définie par count.

Définition : Dans l’API Web Search de Brave, offset est un décalage de page dont la numérotation commence à zéro. Il compte les pages de résultats de la taille définie par count : le décalage de la page suivante est donc normalement supérieur de un à celui de la page précédente. Brave indique également que des pages consécutives peuvent contenir des résultats communs.

Points clés

Dans sa référence de l’API Web Search, Brave définit offset comme le nombre de pages de résultats de recherche, mesuré en unités de count, à sauter avant de renvoyer un résultat.
count détermine le nombre de résultats web renvoyés, avec un maximum de 20 et une valeur par défaut de 20. Le nombre effectivement renvoyé peut être inférieur au nombre demandé, selon la même référence de l’API.
La référence utilise offset=0 pour la page au décalage 0 et indique d’augmenter offset de 1 pour chaque page suivante, avec 0, 1 et 2 comme exemple de séquence.
La documentation des exemples de code de l’API Web Search de Brave présente la page 2 avec count=20&offset=1.
Plusieurs pages peuvent contenir des résultats communs, et le champ query.more_results_available de la réponse indique si d’autres pages sont disponibles.

Comment fonctionne l’unité de décalage ?

La référence de l’API associe count et offset. count correspond au nombre de résultats de recherche demandé dans la réponse. Il s’applique aux résultats web, avec un minimum de 1, un maximum de 20 et une valeur par défaut de 20. Le nombre effectivement renvoyé peut être inférieur au nombre demandé.

offset commence à 0. La référence le décrit comme le nombre de pages de résultats de taille count à sauter, avec une valeur par défaut de 0 et un maximum de 9. Avec count=10, le décalage 0 correspond à la page de départ de la séquence, le décalage 1 à la position de la page suivante et le décalage 2 à celle de la page qui suit. L’unité est une position de page. Les résultats individuels sont repérés en combinant la taille de page et le décalage de page.

count=10&offset=0
count=10&offset=1
count=10&offset=2

La séquence du bloc de code suit l’exemple de Brave, qui augmente le décalage de 1 pour chaque page suivante. Elle n’implique pas que chaque réponse contienne exactement 10 résultats, car la référence précise que le nombre effectivement renvoyé peut être inférieur.

Que montre le second guide de pagination de Brave ?

La documentation des exemples de code de l’API Web Search de Brave décrit count comme le nombre maximal de résultats par page, avec un maximum et une valeur par défaut de 20. Elle décrit offset comme une position de départ numérotée à partir de zéro et présente offset=1 comme la page 2 lorsque la requête demande jusqu’à 20 résultats par page.

curl "https://api.search.brave.com/res/v1/web/search?q=open+source+projects&count=20&offset=1" \
  -H "X-Subscription-Token: <YOUR_API_KEY>"

Cet exemple confirme que le paramètre s’exprime en pages. Il fournit aussi un modèle concret de requête pour la deuxième position de page : conserver la requête de recherche et le nombre de résultats demandé, puis faire passer le décalage de 0 à 1.

Comment un client doit-il gérer les résultats communs et la fin de la séquence ?

La référence de l’API indique explicitement que plusieurs pages peuvent contenir des résultats communs. Un client qui regroupe des pages doit donc comparer les URL des résultats renvoyés avant de présenter une liste fusionnée, tout en conservant l’ordre initial des pages pour le suivi de la pagination.

La même référence expose more_results_available dans l’objet query de la réponse et le définit comme un indicateur de disponibilité de résultats supplémentaires pour la pagination. La documentation des exemples de code indique de consulter ce champ avant de demander la page suivante et de ne la demander que lorsque sa valeur est true.

{
  "query": {
    "original": "open source projects",
    "more_results_available": true
  }
}

Le décalage maximal documenté est 9. Un client doit donc aussi s’appuyer sur le champ de l’API qui indique si la pagination peut se poursuivre pour déterminer si une autre requête est appropriée, plutôt que de supposer qu’une page supplémentaire existe pour chaque décalage de 0 à 9.

Termes associés

Questions fréquentes

Si je demande 10 résultats, quel doit être le décalage suivant ?

Utilisez le décalage 1 après une page demandée avec count=10. La séquence documentée utilise count=10 avec les décalages 0, 1, 2, et ainsi de suite. Le décalage avance par page, tandis que count définit la taille de page demandée.

Puis-je supposer que chaque page contient le nombre de résultats demandé ?

Non. Brave indique que le nombre effectivement renvoyé peut être inférieur au nombre demandé et que plusieurs pages peuvent contenir des résultats communs. Conservez l’URL de chaque résultat lors de la fusion des pages et gérez les doublons.

Quand dois-je arrêter de demander des pages ?

Consultez query.more_results_available. La documentation des exemples de code de Brave indique de ne demander la page suivante que lorsque ce champ vaut true.

Sources

Vérifiez comment une page se lit pour les moteurs de réponse. Ouvrir l’analyseur de score GEO

Le paramètre offset de Brave compte-t-il les résultats ou les pages de résultats ?