検索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"

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

ストレージ

検索のために保存されたファイルはデフォルトで7日間保持されます。POST /v1/searchesでstorageオブジェクトを渡すことで、より長く、または無期限に保持することができます。この設定は、result.json_hosted_urlでホストされているJSONファイルと、scrape_optionsが設定されている場合は各リンクのスクレイピングされたコンテンツに適用されます。

パラメータ	タイプ	デフォルト	説明
`storage.expires_in`	`string`	`7d`	保存されたファイルを保持する期間。`7d`、`10d`、`30d`、`60d`、`90d`、`180d`、`365d`、または`never`（無期限）のいずれか。

storageを省略するか、expires_inなしでstorageを送信すると、7dが使用されます。作成レスポンスとGET /v1/searches/{search_id}には、実際の値が含まれます：

"storage": { "expires_in": "30d" }

cURL

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best open source vector databases",
    "storage": { "expires_in": "30d" }
  }'

無効な値は400を返します：

{
  "type": "invalid_request_error",
  "message": "Invalid storage.expires_in. Allowed values: \"7d\", \"10d\", \"30d\", \"60d\", \"90d\", \"180d\", \"365d\", \"never\".",
  "code": "invalid_storage_expires_in"
}

料金

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

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

開始する

機能

残高と請求書

インストール

基本的な使い方

リクエストパラメータ

結果の数を制限する

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

scrape_options

動作

スクレイピングの例

レスポンス

過去の検索を取得する

ストレージ

料金

​インストール

​基本的な使い方

​リクエストパラメータ

​結果の数を制限する

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

​scrape_options

​動作

​スクレイピングの例

​レスポンス

​過去の検索を取得する

​ストレージ

​料金

インストール

基本的な使い方

リクエストパラメータ

結果の数を制限する

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

scrape_options

動作

スクレイピングの例

レスポンス

過去の検索を取得する

ストレージ

料金