Zum Hauptinhalt springen

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.

Der Olostep-Endpunkt /v1/searches ermöglicht es dir, das Web mit einer natürlichen Sprachabfrage zu durchsuchen und eine deduplizierte Liste relevanter Links mit Titeln und Beschreibungen zurückzubekommen.
  • Sende eine Abfrage in einfachem Englisch
  • Erhalte strukturierte Links aus dem gesamten Web
  • Optional kannst du jede zurückgegebene URL in einem Durchgang scrapen und markdown_content / html_content direkt in die Antwort einbetten
  • Filtere nach Domain, kontrolliere die Anzahl der Ergebnisse und begrenze die Scraping-Zeit
Es wird semantisch nach der Abfrage im Web gesucht und Ergebnisse werden zurückgegeben. Für API-Details siehe die API-Referenz des Suchendpunkts.

​
Installation

pip install olostep

​
Grundlegende Nutzung

Sende eine natürliche Sprachabfrage und erhalte eine Liste relevanter Links. 
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))

​
Anfrageparameter

FeldTypErforderlichStandardBeschreibung
querystringja—Die Suchabfrage in natürlicher Sprache.
limitintegernein12Maximale Anzahl von Links, die nach Deduplikation zurückgegeben werden. Muss zwischen 1 und 25 liegen.
include_domainsstring[]nein[]Beschränke Ergebnisse auf diese Domains. Nur Hosts — führende http(s):// und abschließende Schrägstriche werden automatisch entfernt.
exclude_domainsstring[]nein[]Schließe Ergebnisse von diesen Domains aus. Nur Hosts — führende http(s):// und abschließende Schrägstriche werden automatisch entfernt.
scrape_optionsobjectnein—Wenn angegeben, wird jeder zurückgegebene Link auch gescrapt und sein Inhalt in die Antwort eingebettet. Siehe scrape_options unten.

​
Begrenzung der Anzahl der Ergebnisse

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

​
Filtern nach Domain

include_domains beschränkt Ergebnisse auf eine Whitelist; exclude_domains filtert unerwünschte Quellen aus. Sie können kombiniert werden. 
{
  "query": "OpenAI Sora shutdown analysis",
  "include_domains": ["nytimes.com", "wsj.com", "bbc.com"],
  "exclude_domains": ["pinterest.com"]
}

​
scrape_options

Übergebe scrape_options, um jede zurückgegebene URL parallel zu scrapen und den gerenderten Inhalt direkt auf jedem Link einzubetten. Dies spart einen Durchgang pro Ergebnis im Vergleich zum separaten Aufruf von /v1/searches und /v1/scrapes. 
{
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 10,
  "scrape_options": {
    "formats": ["markdown"],
    "remove_css_selectors": "default",
    "timeout": 25
  }
}
FeldTypStandardBeschreibung
formatsstring[]["markdown"]Ausgabeformate, die jedem Link angehängt werden. Für /v1/searches werden nur "html" und "markdown" unterstützt. Übergebe ["html", "markdown"], um beide zu erhalten.
remove_css_selectorsstring"default"Weitergeleitet an /v1/scrapes. "default" entfernt Navigations-/Fußzeilen-/Skript-/Stil-/SVG-/Dialoggeräusche. Verwende "none", um es zu deaktivieren, oder übergebe ein JSON-String-Array von Selektoren, die entfernt werden sollen.
timeoutinteger25Zeitbudget in Sekunden für die gesamte Scrape-Phase. Muss zwischen 1 und 60 liegen. Wenn diese Zeit abläuft, wird die Suche sofort zurückgegeben — Inhaltsfelder sind null für alle Links, die noch nicht fertig sind.

​
Verhalten

  • Alle Links werden parallel gescrapt. Der timeout begrenzt das gesamte Batch, nicht jeden einzelnen Link.
  • Bei Scraping-Fehlern pro Link (Netzwerkfehler, individuelle Seitenauszeiten) bleibt der markdown_content / html_content dieses Links null, während andere Links normal zurückgegeben werden.
  • Wenn der globale timeout abläuft, bevor alle Scrapes abgeschlossen sind, antwortet die Suche sofort mit den Links, die sie hat — bereits abgeschlossene Scrapes behalten ihren Inhalt; in Bearbeitung befindliche kommen mit null Inhalt zurück.
  • Für reddit.com/.../comments/... URLs wird die Anfrage automatisch durch den @olostep/reddit-post Parser geleitet und das strukturierte JSON wird in sauberes Markdown + einfaches HTML gerendert.
  • Wenn der kombinierte Inline-Inhalt 9 MB überschreitet, werden Inhaltsfelder genullt, result.size_exceeded wird auf true gesetzt und du kannst die vollständige Nutzlast von result.json_hosted_url abrufen.

​
Beispiel mit 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")

​
Antwort

Du erhältst ein search-Objekt als Antwort. Das search-Objekt enthält eine id, deine ursprüngliche query, credits_consumed und ein result mit einer Liste von 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..."
      }
    ]
  }
}
Jeder Link in result.links enthält:
FeldTypBeschreibung
urlstringDie URL des Suchergebnisses.
titlestringDer Titel der Ergebnis-Seite.
descriptionstringEin kurzer Ausschnitt, der das Ergebnis beschreibt.
markdown_contentstringMarkdown-Inhalt der Seite. Nur vorhanden, wenn scrape_options.formats "markdown" enthält. null, wenn das Scraping fehlschlug, leer war oder das globale Timeout erreicht wurde.
html_contentstringHTML-Inhalt der Seite. Nur vorhanden, wenn scrape_options.formats "html" enthält. null bei Fehler/Timeout.
Das vollständige Ergebnis ist auch als gehostete JSON-Datei unter result.json_hosted_url verfügbar — nützlich, wenn result.size_exceeded true ist.

​
Abrufen einer früheren Suche

GET /v1/searches/{search_id} gibt alles zurück, was zum Zeitpunkt der Suche gespeichert wurde, einschließlich gescrapten Inhalts. Es ist ein reiner idempotenter Lesevorgang — kein erneutes Scraping, keine erneute Abrechnung. Ältere Suchen ohne scrape_options haben einfach keine Inhaltsfelder pro 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))
Siehe Suche abrufen für vollständige Details.

​
Preisgestaltung

Jede Suche kostet 5 Credits für die Suche selbst. Wenn scrape_options angegeben ist, wird jede gescrapte Seite zum Standardtarif von /v1/scrapes berechnet (typischerweise 1 Credit pro Seite; einige Parser kosten mehr). Die Gesamtsumme wird in credits_consumed zurückgegeben. Beispiele:
Anfragecredits_consumed
Nur Suche5
Suche + 5 gescrapte Seiten (je 1 Credit)10