メインコンテンツへスキップ
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" はナビゲーション/フッター/スクリプト/スタイル/svg/ダイアログのノイズを削除します。"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 ページあたり 1 クレジット。一部のパーサーはそれ以上のコストがかかる場合があります）。合計は credits_consumed に返されます。 例：
リクエストcredits_consumed
検索のみ5
検索 + 5 ページのスクレイピング（各 1 クレジット）10