API de recherche

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 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 de récupération

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

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 récupéré 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 étendue.

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 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	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-stringifié à supprimer.
`timeout`	integer	`25`	Budget en secondes pour toute la phase de récupération. Doit être entre `1` et `60`. Après ce délai, la recherche retourne 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 de page individuelle) 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 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 9MB, 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")

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

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

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 récupération

Réponse

Récupérer une recherche passée

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 récupération

​Réponse

​Récupérer une recherche passée

​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 récupération

Réponse

Récupérer une recherche passée

Tarification