API de Recherche

Le point d’accès Olostep /v1/searches vous 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.

Envoyez une requête en anglais simple
Recevez 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’extraction

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, consultez la Référence de l’API du point d’accès de Recherche.

Installation

pip install olostep

npm install olostep

# curl est disponible par défaut sur macOS, Linux et Windows

npm install node-fetch

pip install requests

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

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

const search = await client.searches.create('Best Answer Engine Optimization startups')

console.log(search.id, search.links.length)

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Best Answer Engine Optimization startups"
  }'

const res = await fetch('https://api.olostep.com/v1/searches', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'Best Answer Engine Optimization startups'
  })
})
console.log(await res.json())

import requests, json

endpoint = "https://api.olostep.com/v1/searches"
payload = {
  "query": "Best Answer Engine Optimization startups"
}
headers = {"Authorization": "Bearer <YOUR_API_KEY>", "Content-Type": "application/json"}

response = requests.post(endpoint, json=payload, headers=headers)
print(json.dumps(response.json(), indent=2))

Paramètres de la requête

Champ	Type	Requis	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 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 extrait et son contenu intégré dans la réponse. Voir scrape_options ci-dessous.
`fast_mode`	boolean	non	`false`	Demander une recherche directe à faible latence en utilisant votre requête telle quelle. Le mode par défaut effectue un passage de recherche plus large pour une couverture de résultats plus large.

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

Passez scrape_options pour extraire 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	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 en secondes pour toute la phase d’extraction. Doit être entre `1` et `60`. Après cela, 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 extraits en parallèle. Le timeout limite l’ensemble du lot, pas chaque lien individuellement.
Les échecs d’extraction par lien (erreurs réseau, délais d’attente de page 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 extractions ne soient terminées, la recherche répond immédiatement avec les liens qu’elle a — les extractions déjà terminées conservent leur contenu ; celles en cours reviennent avec un contenu null.
Pour les URL 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 en ligne combiné dépasse 9 Mo, les champs de contenu sont annulés, result.size_exceeded est défini sur true, et vous pouvez récupérer la charge utile complète à partir de result.json_hosted_url.

Exemple avec extraction

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

import Olostep, { Format } from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

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

for (const link of search.links) {
  console.log(link.url, '—', (link.markdown_content || '').length, 'chars')
}

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What'"'"'s going on with OpenAI'"'"'s Sora shutting down?",
    "limit": 5,
    "scrape_options": {
      "formats": ["markdown"],
      "timeout": 25
    }
  }'

const res = await fetch('https://api.olostep.com/v1/searches', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: "What's going on with OpenAI's Sora shutting down?",
    limit: 5,
    scrape_options: {
      formats: ['markdown'],
      timeout: 25
    }
  })
})
const data = await res.json()
for (const link of data.result.links) {
  console.log(link.url, '—', (link.markdown_content || '').length, 'chars')
}

import requests, json

endpoint = "https://api.olostep.com/v1/searches"
payload = {
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 5,
  "scrape_options": {
    "formats": ["markdown"],
    "timeout": 25
  }
}
headers = {"Authorization": "Bearer <YOUR_API_KEY>", "Content-Type": "application/json"}

response = requests.post(endpoint, json=payload, headers=headers)
data = response.json()
for link in data["result"]["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 original, 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 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 Markdown de la page. Présent uniquement lorsque `scrape_options.formats` inclut `"markdown"`. `null` si l’extraction a échoué, était vide, ou a atteint le timeout global.
`html_content`	string	Contenu 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 ce qui a été conservé au moment de la recherche, y compris tout contenu extrait. C’est une lecture idempotente pure — pas de ré-extraction, pas de nouvelle facturation. Les recherches plus anciennes sans scrape_options n’ont tout 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))

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

const search = await client.searches.get('search_9bi0sbj9xa')
console.log(search.id, search.links.length)

curl -s "https://api.olostep.com/v1/searches/search_9bi0sbj9xa" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY"

Voir Obtenir une Recherche pour tous les détails.

Stockage

Les fichiers stockés pour une recherche sont conservés pendant 7 jours par défaut. Passez un objet storage sur POST /v1/searches pour les conserver plus longtemps, ou indéfiniment. Le paramètre couvre le fichier JSON hébergé à result.json_hosted_url et, lorsque scrape_options est défini, le contenu extrait pour chaque lien.

Paramètre	Type	Défaut	Description
`storage.expires_in`	`string`	`7d`	Durée de conservation des fichiers stockés. L’un de `7d`, `10d`, `30d`, `60d`, `90d`, `180d`, `365d`, ou `never` (indéfini).

Omettre storage, ou envoyer storage sans expires_in, utilise 7d. La réponse de création et GET /v1/searches/{search_id} incluent la valeur en vigueur :

"storage": { "expires_in": "30d" }

cURL

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best open source vector databases",
    "storage": { "expires_in": "30d" }
  }'

Une valeur invalide retourne 400 :

{
  "type": "invalid_request_error",
  "message": "Invalid storage.expires_in. Allowed values: \"7d\", \"10d\", \"30d\", \"60d\", \"90d\", \"180d\", \"365d\", \"never\".",
  "code": "invalid_storage_expires_in"
}

Tarification

Chaque recherche coûte 5 crédits pour la recherche elle-même. Lorsque scrape_options est fourni, chaque page extraite est facturée au tarif standard de /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 extraites (1 crédit chacune)	`10`

Commencer

Fonctionnalités

Solde et Facturation

Installation

Utilisation de base

Paramètres de la requête

Limiter le nombre de résultats

Filtrer par domaine

scrape_options

Comportement

Exemple avec extraction

Réponse

Récupérer une recherche passée

Stockage

Tarification

​Installation

​Utilisation de base

​Paramètres de la requête

​Limiter le nombre de résultats

​Filtrer par domaine

​scrape_options

​Comportement

​Exemple avec extraction

​Réponse

​Récupérer une recherche passée

​Stockage

​Tarification

Installation

Utilisation de base

Paramètres de la requête

Limiter le nombre de résultats

Filtrer par domaine

scrape_options

Comportement

Exemple avec extraction

Réponse

Récupérer une recherche passée

Stockage

Tarification