API di Ricerca

L’endpoint Olostep /v1/searches ti permette di cercare sul web con una query in linguaggio naturale e ottenere una lista deduplicata di link rilevanti con titoli e descrizioni.

Invia una query in inglese semplice
Ottieni link strutturati da tutto il web
Facoltativamente, esegui il scraping di ogni URL restituito in un solo round-trip e incorpora markdown_content / html_content direttamente nella risposta
Filtra per dominio, controlla il numero di risultati e limita il tempo di scraping

Effettuerà una ricerca semantica della query sul web e restituirà i risultati. Per i dettagli dell’API, consulta la Riferimento API Endpoint di Ricerca.

Installazione

pip install olostep

npm install olostep

# curl è disponibile di default su macOS, Linux e Windows

npm install node-fetch

pip install requests

Uso di base

Invia una query in linguaggio naturale e ricevi una lista di link rilevanti.

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

Parametri della richiesta

Campo	Tipo	Obbligatorio	Default	Descrizione
`query`	string	sì	—	La query di ricerca in linguaggio naturale.
`limit`	integer	no	`12`	Numero massimo di link da restituire dopo la deduplicazione. Deve essere tra `1` e `25`.
`include_domains`	string[]	no	`[]`	Restringi i risultati a questi domini. Solo host nudi — `http(s)://` iniziali e slash finali vengono rimossi automaticamente.
`exclude_domains`	string[]	no	`[]`	Escludi risultati da questi domini. Solo host nudi — `http(s)://` iniziali e slash finali vengono rimossi automaticamente.
`scrape_options`	object	no	—	Quando fornito, ogni link restituito viene anche sottoposto a scraping e il suo contenuto incorporato nella risposta. Vedi scrape_options sotto.
`fast_mode`	boolean	no	`false`	Richiedi una ricerca diretta e a bassa latenza usando la tua query alla lettera. La modalità predefinita esegue una ricerca più ampia per una copertura di risultati più ampia.

Limitare il numero di risultati

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

Filtrare per dominio

include_domains restringe i risultati a una whitelist; exclude_domains filtra le fonti indesiderate. Possono essere combinati.

{
  "query": "OpenAI Sora shutdown analysis",
  "include_domains": ["nytimes.com", "wsj.com", "bbc.com"],
  "exclude_domains": ["pinterest.com"]
}

scrape_options

Passa scrape_options per eseguire il scraping di ogni URL restituito in parallelo e incorporare il contenuto reso direttamente su ogni link. Questo risparmia un round-trip per risultato rispetto a chiamare /v1/searches e /v1/scrapes separatamente.

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

Campo	Tipo	Default	Descrizione
`formats`	string[]	`["markdown"]`	Formati di output da allegare a ogni link. Per `/v1/searches`, sono supportati solo `"html"` e `"markdown"`. Passa `["html", "markdown"]` per ricevere entrambi.
`remove_css_selectors`	string	`"default"`	Inoltrato a `/v1/scrapes`. `"default"` rimuove rumore di navigazione/piè di pagina/script/stile/svg/dialogo. Usa `"none"` per disabilitare, o passa un array JSON-stringificato di selettori da rimuovere.
`timeout`	integer	`25`	Budget di wallclock in secondi per l’intera fase di scraping. Deve essere tra `1` e `60`. Dopo questo tempo, la ricerca restituisce immediatamente — i campi di contenuto saranno `null` per i link che non sono stati completati.

Comportamento

Tutti i link vengono sottoposti a scraping in parallelo. Il timeout limita l’intero batch, non ogni singolo link.
I fallimenti di scraping per singolo link (errori di rete, timeout della pagina individuale) lasciano il markdown_content / html_content di quel link come null mentre gli altri link vengono restituiti normalmente.
Se il timeout globale scade prima che tutti gli scraping siano completati, la ricerca risponde immediatamente con i link che ha — gli scraping già completati mantengono il loro contenuto; quelli in corso tornano con contenuto null.
Per gli URL reddit.com/.../comments/..., la richiesta viene automaticamente instradata attraverso il parser @olostep/reddit-post e il JSON strutturato viene reso in markdown pulito + HTML di base
Se il contenuto combinato in linea supera i 9MB, i campi di contenuto vengono annullati, result.size_exceeded viene impostato su true, e puoi recuperare il payload completo da result.json_hosted_url.

Esempio con scraping

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

Risposta

Riceverai un oggetto search in risposta. L’oggetto search contiene un id, la tua query originale, credits_consumed, e un result con una lista di 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..."
      }
    ]
  }
}

Ogni link in result.links contiene:

Campo	Tipo	Descrizione
`url`	string	L’URL del risultato di ricerca.
`title`	string	Il titolo della pagina del risultato.
`description`	string	Un breve frammento che descrive il risultato.
`markdown_content`	string	Contenuto markdown della pagina. Presente solo quando `scrape_options.formats` include `"markdown"`. `null` se il scraping è fallito, era vuoto o ha raggiunto il timeout globale.
`html_content`	string	Contenuto HTML della pagina. Presente solo quando `scrape_options.formats` include `"html"`. `null` in caso di fallimento/timeout.

Il risultato completo è anche disponibile come file JSON ospitato su result.json_hosted_url — utile quando result.size_exceeded è true.

Recuperare una ricerca passata

GET /v1/searches/{search_id} restituisce ciò che è stato conservato al momento della ricerca, incluso qualsiasi contenuto sottoposto a scraping. È una lettura idempotente pura — nessun nuovo scraping, nessuna nuova fatturazione. Le ricerche più vecchie senza scrape_options semplicemente non hanno campi di contenuto per link.

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"

Consulta Get Search per i dettagli completi.

Prezzi

Ogni ricerca costa 5 crediti per la ricerca stessa. Quando scrape_options è fornito, ogni pagina sottoposta a scraping viene addebitata al tasso standard di /v1/scrapes (tipicamente 1 credito per pagina; alcuni parser costano di più). Il totale è restituito in credits_consumed. Esempi:

Richiesta	`credits_consumed`
Solo ricerca	`5`
Ricerca + 5 pagine sottoposte a scraping (1 credito ciascuna)	`10`

Inizia

Funzionalità

Saldo e Fatturazione

Installazione

Uso di base

Parametri della richiesta

Limitare il numero di risultati

Filtrare per dominio

scrape_options

Comportamento

Esempio con scraping

Risposta

Recuperare una ricerca passata

Prezzi

​Installazione

​Uso di base

​Parametri della richiesta

​Limitare il numero di risultati

​Filtrare per dominio

​scrape_options

​Comportamento

​Esempio con scraping

​Risposta

​Recuperare una ricerca passata

​Prezzi

Installazione

Uso di base

Parametri della richiesta

Limitare il numero di risultati

Filtrare per dominio

scrape_options

Comportamento

Esempio con scraping

Risposta

Recuperare una ricerca passata

Prezzi