API de recherche - Olostep Docs

Le point de terminaison Olostep /v1/searches vous permet de rechercher sur le web avec une requête en langage naturel et de recevoir une liste dédupliquée de liens pertinents avec des titres et des descriptions.

Envoyez une requête en anglais courant
Obtenez des liens structurés de tout le web
Optionnellement, récupérez chaque URL retournée en un seul aller-retour et intégrez markdown_content / html_content directement dans la réponse
Filtrez par domaine, contrôlez le nombre de résultats et limitez le temps d’exécution du scraping

Il recherchera la requête de manière sémantique sur le web et renverra les résultats. Pour les détails de l’API, consultez la Référence de l’API du point de terminaison de recherche.

Installation

pip install olostep

Utilisation de base

Envoyez une requête en langage naturel et recevez 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

Champ	Type	Requis	Par défaut	Description
`query`	string	oui	—	La requête de recherche en langage naturel.
`limit`	integer	non	`12`	Nombre maximum de liens à retourner après déduplication. Doit être compris entre `1` et `25`.
`include_domains`	string[]	non	`[]`	Restreindre les résultats à ces domaines. Hôtes nus uniquement — les préfixes `http(s)://` et les barres obliques finales sont automatiquement supprimés.
`exclude_domains`	string[]	non	`[]`	Exclure 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_options`	object	non	—	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 limite 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

Passez 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 de /v1/searches et /v1/scrapes séparément.

{
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 10,
  "scrape_options": {
    "formats": ["markdown"],
    "remove_css_selectors": "default",
    "timeout": 25
  }
}

Champ	Type	Par défaut	Description
`formats`	string[]	`["markdown"]`	Formats de sortie à attacher à chaque lien. Pour `/v1/searches`, seuls `"html"` et `"markdown"` sont pris en charge. Passez `["html", "markdown"]` pour recevoir les deux.
`remove_css_selectors`	string	`"default"`	Transmis à `/v1/scrapes`. `"default"` supprime le bruit nav/footer/script/style/svg/dialog. Utilisez `"none"` pour désactiver, ou passez un tableau de sélecteurs JSON pour supprimer.
`timeout`	integer	`25`	Budget d’exécution en secondes pour toute la phase de récupération. Doit être compris entre `1` et `60`. Après ce délai, la recherche revient immédiatement — les champs de contenu seront `null` pour tous les liens qui n’ont pas été terminés.

Comportement

Tous les liens sont récupérés en parallèle. Le timeout limite l’ensemble du lot, pas chaque lien individuel.
Les échecs de récupération par lien (erreurs réseau, délais d’attente individuels) 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 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 acheminée via le parseur @olostep/reddit-post et le JSON structuré est rendu en markdown propre + HTML basique.
Si le contenu intégré combiné dépasse 9 Mo, les champs de contenu sont annulés, result.size_exceeded est défini à true, et vous pouvez 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

Vous recevrez un objet search en réponse. L’objet search contient un id, votre 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 :

Champ	Type	Description
`url`	string	L’URL du résultat de la recherche.
`title`	string	Le titre de la page de résultat.
`description`	string	Un court extrait décrivant le résultat.
`markdown_content`	string	Contenu en 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 délai d’attente global.
`html_content`	string	Contenu HTML de la page. Présent uniquement lorsque `scrape_options.formats` inclut `"html"`. `null` en cas d’échec/délai d’attente.

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 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))

Voir Get Search pour plus de 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ête	`credits_consumed`
Recherche uniquement	`5`
Recherche + 5 pages récupérées (1 crédit chacune)	`10`

​Installation

​Utilisation de base

​Paramètres de la requête

​Limiter le nombre de résultats

​Filtrer par domaine

​scrape_options

​Comportement

​Exemple avec récupération

​Réponse

​Récupérer une recherche passée

​Tarification