メインコンテンツへスキップ

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.

Olostep の /v1/searches エンドポイントを使用すると、自然言語クエリでウェブを検索し、タイトルと説明が付いた重複排除された関連リンクのリストを取得できます。
  • クエリをプレーンな英語で送信
  • ウェブ全体から構造化されたリンクを取得
  • オプションで返されたすべての URL を一度にスクレイピングし、markdown_content / html_content を直接レスポンスに埋め込む
  • ドメインでフィルタリングし、結果の数を制御し、スクレイピングのウォールクロックを制限
クエリをウェブ全体で意味的に検索し、結果を返します。 API の詳細については、検索エンドポイント API リファレンスを参照してください。

​
インストール

pip install olostep

​
基本的な使い方

自然言語クエリを送信し、関連するリンクのリストを受け取ります。 
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))

​
リクエストパラメータ

フィールドタイプ必須デフォルト説明
querystringyes—自然言語での検索クエリ。
limitintegerno12重複排除後に返すリンクの最大数。1 から 25 の間で指定。
include_domainsstring[]no[]結果をこれらのドメインに制限。プレーンなホストのみ — 先頭の http(s):// と末尾のスラッシュは自動で削除されます。
exclude_domainsstring[]no[]これらのドメインからの結果を除外。プレーンなホストのみ — 先頭の http(s):// と末尾のスラッシュは自動で削除されます。
scrape_optionsobjectno—指定された場合、返されたすべてのリンクがスクレイピングされ、その内容がレスポンスに埋め込まれます。以下の scrape_options を参照。

​
結果の数を制限する

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

​
ドメインでフィルタリングする

include_domains は結果をホワイトリストに絞り、exclude_domains は不要なソースを除外します。これらは組み合わせることができます。 
{
  "query": "OpenAI Sora shutdown analysis",
  "include_domains": ["nytimes.com", "wsj.com", "bbc.com"],
  "exclude_domains": ["pinterest.com"]
}

​
scrape_options

scrape_options を渡して、返されたすべての URL を並行してスクレイピングし、レンダリングされたコンテンツを各リンクに直接埋め込みます。これにより、/v1/searches と /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
  }
}
フィールドタイプデフォルト説明
formatsstring[]["markdown"]各リンクに添付する出力フォーマット。/v1/searches では "html" と "markdown" のみサポート。["html", "markdown"] を渡すと両方を受け取れます。
remove_css_selectorsstring"default"/v1/scrapes に転送されます。"default" は nav/footer/script/style/svg/dialog のノイズを削除します。"none" を指定すると無効化され、削除するセレクタの JSON 文字列化された配列を渡すこともできます。
timeoutinteger25スクレイプフェーズ全体のウォールクロック予算（秒単位）。1 から 60 の間で指定。これが経過すると、検索は即座に返され、完了していないリンクのコンテンツフィールドは null になります。

​
動作

  • すべてのリンクは並行してスクレイピングされます。timeout はバッチ全体を制限し、各リンク個別ではありません。
  • リンクごとのスクレイプ失敗（ネットワークエラー、個別ページのタイムアウト）は、そのリンクの markdown_content / html_content を null にし、他のリンクは通常通り返されます。
  • グローバル timeout がすべてのスクレイプが完了する前に経過した場合、検索は即座に完了したリンクを持って応答します。すでに完了したスクレイプはそのコンテンツを保持し、進行中のものは null コンテンツで返されます。
  • reddit.com/.../comments/... の URL については、リクエストが自動的に @olostep/reddit-post パーサーを通じてルーティングされ、構造化された JSON がクリーンなマークダウン + 基本的な HTML にレンダリングされます。
  • 結合されたインラインコンテンツが 9MB を超える場合、コンテンツフィールドは無効化され、result.size_exceeded が true に設定され、result.json_hosted_url から完全なペイロードを取得できます。

​
スクレイピングの例

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

​
レスポンス

レスポンスには search オブジェクトが含まれます。search オブジェクトには id、元の query、credits_consumed、および links のリストを含む result が含まれます。 
{
  "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..."
      }
    ]
  }
}
result.links の各リンクには以下が含まれます：
フィールドタイプ説明
urlstring検索結果の URL。
titlestring結果ページのタイトル。
descriptionstring結果を説明する短いスニペット。
markdown_contentstringページのマークダウンコンテンツ。scrape_options.formats に "markdown" が含まれる場合のみ存在。スクレイプが失敗した場合、空の場合、またはグローバルタイムアウトに達した場合は null。
html_contentstringページの HTML コンテンツ。scrape_options.formats に "html" が含まれる場合のみ存在。失敗/タイムアウト時は null。
完全な結果は result.json_hosted_url でホストされた JSON ファイルとしても利用可能です — result.size_exceeded が true の場合に便利です。

​
過去の検索を取得する

GET /v1/searches/{search_id} は、検索時に保存された内容を返します。スクレイプされたコンテンツも含まれます。これは純粋な冪等の読み取りであり、再スクレイピングや再請求はありません。scrape_options のない古い検索には、リンクごとのコンテンツフィールドがありません。 
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))
詳細は 検索を取得 を参照してください。

​
価格

各検索は検索自体に対して 5 クレジット かかります。 scrape_options が提供されている場合、各スクレイプされたページは標準の /v1/scrapes レートで請求されます（通常はページあたり 1 クレジット、一部のパーサーはそれ以上かかる場合があります）。合計は credits_consumed に返されます。 例：
リクエストcredits_consumed
検索のみ5
検索 + 5 ページのスクレイプ（各 1 クレジット）10