Vai al contenuto principale

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.

L’endpoint Olostep /v1/searches ti permette di cercare sul web con una query in linguaggio naturale e ottenere un elenco deduplicato di link rilevanti con titoli e descrizioni.
  • Invia una query in inglese semplice
  • Ricevi link strutturati da tutto il web
  • Facoltativamente, effettua lo 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 su tutto il web e restituirà i risultati. Per i dettagli dell’API, consulta il Riferimento API dell’Endpoint di Ricerca.

​
Installazione

pip install olostep

​
Uso di base

Invia una query in linguaggio naturale e ricevi un elenco 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))

​
Parametri della richiesta

CampoTipoObbligatorioDefaultDescrizione
querystringsì—La query di ricerca in linguaggio naturale.
limitintegerno12Numero massimo di link da restituire dopo la deduplicazione. Deve essere tra 1 e 25.
include_domainsstring[]no[]Restringi i risultati a questi domini. Solo host nudi — http(s):// iniziali e slash finali vengono rimossi automaticamente.
exclude_domainsstring[]no[]Escludi i risultati da questi domini. Solo host nudi — http(s):// iniziali e slash finali vengono rimossi automaticamente.
scrape_optionsobjectno—Quando fornito, ogni link restituito viene anche sottoposto a scraping e il suo contenuto incorporato nella risposta. Vedi scrape_options sotto.

​
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 effettuare lo 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
  }
}
CampoTipoDefaultDescrizione
formatsstring[]["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_selectorsstring"default"Inoltrato a /v1/scrapes. "default" rimuove rumore di nav/footer/script/style/svg/dialog. Usa "none" per disabilitare, o passa un array di selettori JSON-stringificato da rimuovere.
timeoutinteger25Budget di tempo 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 eventuali link non 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 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 indirizzata attraverso il parser @olostep/reddit-post e il JSON strutturato viene reso in markdown pulito + HTML di base.
  • Se il contenuto inline combinato supera i 9MB, i campi di contenuto vengono annullati, result.size_exceeded è 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")

​
Risposta

Riceverai un oggetto search in risposta. L’oggetto search contiene un id, la tua query originale, credits_consumed e un result con un elenco 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:
CampoTipoDescrizione
urlstringL’URL del risultato di ricerca.
titlestringIl titolo della pagina del risultato.
descriptionstringUn breve snippet che descrive il risultato.
markdown_contentstringContenuto markdown della pagina. Presente solo quando scrape_options.formats include "markdown". null se lo scraping è fallito, era vuoto o ha raggiunto il timeout globale.
html_contentstringContenuto 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 salvato 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))
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 fatturata al tasso standard di /v1/scrapes (tipicamente 1 credito per pagina; alcuni parser costano di più). Il totale è restituito in credits_consumed. Esempi:
Richiestacredits_consumed
Solo ricerca5
Ricerca + 5 pagine sottoposte a scraping (1 credito ciascuna)10