Aller au contenu

Documentation

Endpoints

Une même recherche, quatre niveaux de détail : chaque endpoint renvoie les mêmes sources classées par pertinence, plus ou moins complètes, et a son propre prix.

POST https://platform.ibou.com/api/v1/…
Endpoints et prix
EndpointsChaque résultat contient
/v1/urls 1 unitéL’URL de la source.
/v1/results 2 unitésL’hôte, l’URL, le titre, un extrait et la langue de la source.
/v1/passage 3 unitésComme /v1/results, plus le passage le plus pertinent.
/v1/page 5 unitésComme /v1/results, plus tous les passages de la page.

Authentification

Chaque requête doit contenir une des clés API de votre organisation dans l’en-tête X-API-Key. Créez et gérez vos clés sur la page Clés API.

Pour essayer sans écrire de code, le Playground lance une recherche avec les unités de votre organisation, sans clé à saisir.

Requête

Champs de la requête
ChampDescription
query chaîne, obligatoire La question de recherche, non vide. 200 caractères maximum.
max_results entier, facultatif Nombre de résultats à renvoyer, entre 1 et 20. 10 par défaut.

Exemple

Exemple de requête cURL

curl -X POST https://platform.ibou.com/api/v1/passage \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{ "query": "pourquoi le ciel est bleu" }'

Réponse

Un objet JSON, ici pour /v1/passage, réduit à ses trois premiers résultats :

Exemple de réponse

{
  "query": "pourquoi le ciel est bleu",
  "max_results": 10,
  "results": [
    {
      "host": "meteofrance.com",
      "url": "https://meteofrance.com/meteo-a-z/pourquoi-le-ciel-est-il-bleu",
      "title": "Pourquoi le ciel est-il bleu ? | Météo-France",
      "snippet": "Pourquoi le ciel est-il rouge le soir ? · Au moment du lever et du coucher du soleil, la lumière du soleil traverse une plus grande épaisseur d’atmosphère avant de parvenir jusqu’à notre œil. Sur ce long chemin dans l’atmosphère, les rayonnements de petites…",
      "language": "fr",
      "passage": {
        "chunk_id": 1,
        "text": "[Pourquoi le ciel est-il bleu ? | Météo-France]\n[## Pourquoi le ciel est-il rouge le soir ?]\nAu moment du lever et du coucher du soleil, la lumière du soleil traverse une plus grande épaisseur d’atmosphère avant de parvenir jusqu’à notre œil. Sur ce long chemin dans l’atmosphère, les rayonnements de petites longueurs d’onde, comme le bleu, sont complètement diffusés ; ce sont les couleurs orangées ou rouges, de plus grandes longueurs d’onde, qui vont parvenir à arriver jusqu’à nous pour embellir notre ciel de début ou fin de journée.\n"
      }
    },
    {
      "host": "www.meteo.be",
      "url": "https://www.meteo.be/fr/infos/faq/phenomenes-meteorologiques/pourquoi-le-ciel-est-il-bleu",
      "title": "IRM - Pourquoi le ciel est-il bleu?",
      "snippet": "FAQ · Phénomènes météorologiques · Pourquoi le ciel est-il bleu? · La lumière solaire qui atteint la terre est diffusée par les molécules de l’air qu’elle rencontre. Le diamètre de ces molécules est beaucoup plus petit que celui des gouttelettes d’eau et…",
      "language": "fr",
      "passage": {
        "chunk_id": 0,
        "text": "[IRM - Pourquoi le ciel est-il bleu?]\n[# FAQ]\n[## Phénomènes météorologiques]\n[### Pourquoi le ciel est-il bleu?]\nLa lumière solaire qui atteint la terre est diffusée par les molécules de l’air qu’elle rencontre.\nLe diamètre de ces molécules est beaucoup plus petit que celui des gouttelettes d’eau et aussi plus petit que la longueur d’onde de la lumière visible (entre 0,4 et 0,7 micromètres).\nLes molécules composant l’air (essentiellement l’azote et l’oxygène) diffusent la lumière des courtes longueurs d’ondes (dans le violet et le bleu) nettement mieux que les longues (dans le rouge et l’orange). C’est ce qui explique qu’en observant un ciel dégagé de nuage, il nous apparaisse bleu.\nVous n'aimez pas notre image de fond? Pas de problème; il vous suffit de cocher la case ci-dessous pour désactiver cette image\n"
      }
    },
    {
      "host": "www.rtbf.be",
      "url": "https://www.rtbf.be/article/pourquoi-le-ciel-est-il-bleu-11498508",
      "title": "Pourquoi le ciel est-il bleu ? - RTBF Actus",
      "snippet": "Une question de longueurs d’ondes · En fait, la couleur bleue du ciel n’est pas une fatalité : elle dépend principalement de la longueur d’onde des couleurs. Pour comprendre, il faut savoir que le soleil diffuse de la lumière dite blanche, qui est en réalité…",
      "language": "fr",
      "passage": {
        "chunk_id": 0,
        "text": "[Pourquoi le ciel est-il bleu ? - RTBF Actus]\n[## Une question de longueurs d’ondes]\nEn fait, la couleur bleue du ciel n’est pas une fatalité : elle dépend principalement de la longueur d’onde des couleurs. Pour comprendre, il faut savoir que le soleil diffuse de la lumière dite blanche, qui est en réalité un mélange de toutes les couleurs, chacune d’entre elle ayant une longueur d’ondes spécifique : on parle d’ondes plus ou moins courtes ou plus ou moins longues.\n"
      }
    },
    …
  ]
}

Champs de la réponse
ChampDescription
queryLa question envoyée.
max_resultsLe nombre de résultats demandés.
resultsLes résultats, du plus pertinent au moins pertinent. Avec /v1/urls, chaque résultat est simplement l’URL de la source ; sinon, un objet décrit ci-dessous.

Champs d’un résultat

Champs d’un résultat
ChampDescription
hostLe nom d’hôte du site de la source.
urlL’adresse de la source.
titleLe titre de la page.
snippetUn court extrait de la page.
languageLa langue de la page, par exemple fr.
passageLe passage de la page qui correspond le mieux à la question. Uniquement avec /v1/passage.
passages[]Tous les passages de la page. Uniquement avec /v1/page.
passage.chunk_id
passages[].chunk_id
L’identifiant du passage dans la page.
passage.text
passages[].text
Le texte du passage.
passages[].usedSi ce passage a servi à classer le résultat.

Unités

Chaque appel consomme le prix de son endpoint, en unités, sur le solde de votre organisation. Un appel refusé (clé invalide, unités insuffisantes) ne consomme rien. Toutes les clés API de votre organisation partagent le même solde. Consultez-le sur la page Accueil. Les propriétaires peuvent en acheter sur la page Unités & facturation.

Erreurs

Les erreurs sont renvoyées avec un corps JSON et l’un de ces codes de statut :

Codes de statut d’erreur
StatutSignification
400query ou max_results invalide, ou corps de requête qui n’est pas du JSON.
401Clé API manquante ou inconnue.
403Votre organisation est suspendue. Contactez le support.
404Endpoint inconnu : le chemin ne correspond à aucun des endpoints ci-dessus.
408Le corps de la requête n’est pas arrivé à temps.
413Corps de requête de plus de 4 Kio.
415En-tête Content-Type: application/json manquant.
422query absent, champ inconnu, ou champ d’un mauvais type.
429Votre organisation n’a plus d’unités, ou vous envoyez des requêtes trop rapidement.
500Erreur interne. Réessayez ; si cela se reproduit, contactez le support.
502Le service de recherche a échoué. Réessayez dans quelques instants.
503Service de recherche saturé ou momentanément indisponible. Réessayez après le délai en secondes de l’en-tête Retry-After.
504La recherche a pris trop de temps. Réessayez dans quelques instants.