Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.olostep.com/llms.txt

Use this file to discover all available pages before exploring further.

Le point de terminaison Olostep /v1/searches te permet de rechercher sur le web avec une requête en langage naturel et d’obtenir une liste dédupliquée de liens pertinents avec des titres et des descriptions.
  • Envoie une requête en anglais simple
  • Reçois des liens structurés provenant de tout le web
  • Optionnellement, récupère chaque URL retournée en un seul aller-retour et intègre markdown_content / html_content directement dans la réponse
  • Filtre par domaine, contrôle le nombre de résultats, et limite le temps d’exécution du scraping
Il recherchera la requête de manière sémantique sur le web et retournera les résultats. Pour les détails de l’API, consulte la Référence de l’API du point de terminaison de recherche.

​
Installation

pip install olostep

​
Utilisation basique

Envoie une requête en langage naturel et reçois une liste de liens pertinents. 
from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.create("Best Answer Engine Optimization startups")

print(search.id, len(search.links))

​
Paramètres de la requête

ChampTypeRequisPar défautDescription
querystringoui—La requête de recherche en langage naturel.
limitintegernon12Nombre maximum de liens à retourner après déduplication. Doit être entre 1 et 25.
include_domainsstring[]non[]Restreint les résultats à ces domaines. Hôtes nus uniquement — les préfixes http(s):// et les barres obliques finales sont automatiquement supprimés.
exclude_domainsstring[]non[]Exclut les résultats de ces domaines. Hôtes nus uniquement — les préfixes http(s):// et les barres obliques finales sont automatiquement supprimés.
scrape_optionsobjectnon—Lorsqu’il est fourni, chaque lien retourné est également récupéré et son contenu intégré dans la réponse. Voir scrape_options ci-dessous.

​
Limiter le nombre de résultats

{
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 5
}

​
Filtrer par domaine

include_domains restreint les résultats à une liste blanche ; exclude_domains filtre les sources indésirables. Ils peuvent être combinés. 
{
  "query": "OpenAI Sora shutdown analysis",
  "include_domains": ["nytimes.com", "wsj.com", "bbc.com"],
  "exclude_domains": ["pinterest.com"]
}

​
scrape_options

Passe scrape_options pour récupérer chaque URL retournée en parallèle et intégrer le contenu rendu directement sur chaque lien. Cela économise un aller-retour par résultat par rapport à l’appel séparé de /v1/searches et /v1/scrapes. 
{
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 10,
  "scrape_options": {
    "formats": ["markdown"],
    "remove_css_selectors": "default",
    "timeout": 25
  }
}
ChampTypePar défautDescription
formatsstring[]["markdown"]Formats de sortie à attacher à chaque lien. Pour /v1/searches, seuls "html" et "markdown" sont pris en charge. Passe ["html", "markdown"] pour recevoir les deux.
remove_css_selectorsstring"default"Transmis à /v1/scrapes. "default" supprime le bruit nav/footer/script/style/svg/dialog. Utilise "none" pour désactiver, ou passe un tableau JSON de sélecteurs à supprimer.
timeoutinteger25Budget de temps en secondes pour toute la phase de récupération. Doit être entre 1 et 60. Après cette durée, la recherche retourne immédiatement — les champs de contenu seront null pour tous les liens qui n’ont pas terminé.

​
Comportement

  • Tous les liens sont récupérés en parallèle. Le timeout limite le lot entier, pas chaque lien individuel.
  • Les échecs de récupération par lien (erreurs réseau, délais d’attente de pages individuelles) laissent le markdown_content / html_content de ce lien à null tandis que les autres liens retournent normalement.
  • Si le timeout global expire avant que toutes les récupérations ne soient terminées, la recherche répond immédiatement avec les liens qu’elle a — les récupérations déjà terminées conservent leur contenu ; celles en cours reviennent avec un contenu null.
  • Pour les URLs reddit.com/.../comments/..., la requête est automatiquement dirigée via le parseur @olostep/reddit-post et le JSON structuré est rendu en markdown propre + HTML basique.
  • Si le contenu en ligne combiné dépasse 9MB, les champs de contenu sont annulés, result.size_exceeded est défini à true, et tu peux récupérer la charge utile complète depuis result.json_hosted_url.

​
Exemple avec récupération

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.create(
    query="What's going on with OpenAI's Sora shutting down?",
    limit=5,
    scrape_options={"formats": ["markdown"], "timeout": 25},
)

for link in search.links:
    print(link["url"], "—", len(link.get("markdown_content") or ""), "chars")

​
Réponse

Tu recevras un objet search en réponse. L’objet search contient un id, ta query originale, credits_consumed, et un result avec une liste de links. 
{
  "id": "search_9bi0sbj9xa",
  "object": "search",
  "created": 1760327323,
  "metadata": {},
  "query": "What's going on with OpenAI's Sora shutting down?",
  "credits_consumed": 10,
  "result": {
    "json_content": "...",
    "json_hosted_url": "https://olostep-storage.s3.us-east-1.amazonaws.com/search_9bi0sbj9xa.json",
    "size_exceeded": false,
    "credits_consumed": 10,
    "links": [
      {
        "url": "https://www.bbc.com/news/articles/c3w3e467ewqo",
        "title": "OpenAI to shut down Sora video platform",
        "description": "OpenAI says it will discontinue its Sora app...",
        "markdown_content": "# OpenAI to shut down Sora video platform\n\nOpenAI says it will discontinue..."
      },
      {
        "url": "https://www.reddit.com/r/OutOfTheLoop/comments/1s2u847/whats_going_on_with_openais_sora_shutting_down/",
        "title": "What's going on with OpenAI's Sora shutting down?",
        "description": "Reddit thread discussing the shutdown.",
        "markdown_content": "# What's going on with OpenAI's Sora shutting down?\n\n*r/OutOfTheLoop · u/rm-minus-r · 1mo ago*\n\n..."
      }
    ]
  }
}
Chaque lien dans result.links contient :
ChampTypeDescription
urlstringL’URL du résultat de recherche.
titlestringLe titre de la page de résultat.
descriptionstringUn court extrait décrivant le résultat.
markdown_contentstringContenu Markdown de la page. Présent uniquement lorsque scrape_options.formats inclut "markdown". null si la récupération a échoué, était vide, ou a atteint le timeout global.
html_contentstringContenu HTML de la page. Présent uniquement lorsque scrape_options.formats inclut "html". null en cas d’échec/timeout.
Le résultat complet est également disponible sous forme de fichier JSON hébergé à result.json_hosted_url — utile lorsque result.size_exceeded est true.

​
Récupérer une recherche passée

GET /v1/searches/{search_id} retourne tout ce qui a été enregistré au moment de la recherche, y compris tout contenu récupéré. C’est une lecture idempotente pure — pas de nouvelle récupération, pas de nouvelle facturation. Les recherches plus anciennes sans scrape_options n’ont simplement pas de champs de contenu par lien. 
from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.get(search_id="search_9bi0sbj9xa")
print(search.id, len(search.links))
Consulte Obtenir une recherche pour tous les détails.

​
Tarification

Chaque recherche coûte 5 crédits pour la recherche elle-même. Lorsque scrape_options est fourni, chaque page récupérée est facturée au tarif standard /v1/scrapes (généralement 1 crédit par page ; certains parseurs coûtent plus cher). Le total est retourné dans credits_consumed. Exemples :
Requêtecredits_consumed
Recherche uniquement5
Recherche + 5 pages récupérées (1 crédit chacune)10