検索API

Olostepの/v1/searchesエンドポイントを使用すると、自然言語クエリでウェブを検索し、重複を排除した関連リンクのリストをタイトルと説明と共に取得できます。

クエリを平易な英語で送信
ウェブ全体から構造化されたリンクを取得
オプションで返されたすべてのURLを1回のラウンドトリップでスクレイピングし、markdown_content / html_contentを直接レスポンスに埋め込む
ドメインでフィルタリングし、結果の数を制御し、スクレイピングの実行時間を制限

クエリをウェブ全体で意味的に検索し、結果を返します。 APIの詳細については、検索エンドポイントAPIリファレンスを参照してください。

インストール

pip install olostep

npm install olostep

# curlはmacOS、Linux、Windowsでデフォルトで利用可能

npm install node-fetch

pip install requests

基本的な使い方

自然言語クエリを送信し、関連リンクのリストを受け取ります。

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

リクエストパラメータ

フィールド	タイプ	必須	デフォルト	説明
`query`	string	yes	—	自然言語での検索クエリ。
`limit`	integer	no	`12`	重複排除後に返すリンクの最大数。`1`から`25`の間で指定。
`include_domains`	string[]	no	`[]`	結果をこれらのドメインに限定。ホスト名のみ — 先頭の`http(s)://`と末尾のスラッシュは自動的に削除されます。
`exclude_domains`	string[]	no	`[]`	これらのドメインからの結果を除外。ホスト名のみ — 先頭の`http(s)://`と末尾のスラッシュは自動的に削除されます。
`scrape_options`	object	no	—	提供されると、返されたすべてのリンクもスクレイピングされ、そのコンテンツがレスポンスに埋め込まれます。以下のscrape_optionsを参照。
`fast_mode`	boolean	no	`false`	クエリをそのまま使用して直接、低遅延の検索を要求。デフォルトモードは、より広範な結果を得るために広範囲の検索を行います。

結果の数を制限する

{
  "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
  }
}

フィールド	タイプ	デフォルト	説明
`formats`	string[]	`["markdown"]`	各リンクに添付する出力フォーマット。`/v1/searches`では、`"html"`と`"markdown"`のみがサポートされています。両方を受け取るには`["html", "markdown"]`を渡します。
`remove_css_selectors`	string	`"default"`	`/v1/scrapes`に転送されます。`"default"`はナビゲーション/フッター/スクリプト/スタイル/SVG/ダイアログのノイズを削除します。`"none"`を使用して無効にするか、削除するセレクタのJSON文字列化された配列を渡します。
`timeout`	integer	`25`	スクレイピングフェーズ全体の実行時間の予算を秒で指定します。`1`から`60`の間で指定する必要があります。これが経過すると、検索は即座に終了し、完了していないリンクのコンテンツフィールドは`null`になります。

動作

すべてのリンクは並行してスクレイピングされます。timeoutは個々のリンクではなく、全体のバッチを制限します。
リンクごとのスクレイピング失敗（ネットワークエラー、個々のページのタイムアウト）は、そのリンクのmarkdown_content / html_contentをnullにしますが、他のリンクは正常に返されます。
グローバルなtimeoutがすべてのスクレイピングが完了する前に経過すると、検索はすぐに利用可能なリンクで応答します — すでに完了したスクレイピングはそのコンテンツを保持し、進行中のものはnullコンテンツで返されます。
reddit.com/.../comments/... URLの場合、リクエストは自動的に@olostep/reddit-postパーサーを通じてルーティングされ、構造化されたJSONがクリーンなマークダウンと基本的なHTMLにレンダリングされます。
結合されたインラインコンテンツが9MBを超える場合、コンテンツフィールドはnullになり、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")

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

レスポンス

レスポンスでは、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の各リンクには以下が含まれます：

フィールド	タイプ	説明
`url`	string	検索結果のURL。
`title`	string	結果ページのタイトル。
`description`	string	結果を説明する短いスニペット。
`markdown_content`	string	ページのマークダウンコンテンツ。`scrape_options.formats`に`"markdown"`が含まれている場合のみ存在。スクレイピングが失敗した場合、空の場合、またはグローバルタイムアウトに達した場合は`null`。
`html_content`	string	ページの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))

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"

詳細については、検索を取得を参照してください。

料金

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

リクエスト	`credits_consumed`
検索のみ	`5`
検索 + 5ページのスクレイピング（各1クレジット）	`10`

開始する

機能

残高と請求書

インストール

基本的な使い方

リクエストパラメータ

結果の数を制限する

ドメインでフィルタリング

scrape_options

動作

スクレイピングの例

レスポンス

過去の検索を取得する

料金

​インストール

​基本的な使い方

​リクエストパラメータ

​結果の数を制限する

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

​scrape_options

​動作

​スクレイピングの例

​レスポンス

​過去の検索を取得する

​料金

インストール

基本的な使い方

リクエストパラメータ

結果の数を制限する

ドメインでフィルタリング

scrape_options

動作

スクレイピングの例

レスポンス

過去の検索を取得する

料金