/v1/batches 以及你得到的 JSON 的简要概览。
引擎
每个引擎需要其自己的解析器 ID 和 URL 模板。在批处理级别传递解析器一次。将查询编码在 URL 中。| 引擎 | 解析器 | URL 模板 | 积分 | 最大项目数 |
|---|---|---|---|---|
| Google AI 模式 | @olostep/google-aimode-results | https://www.google.com/aimode?q={query} | 3 | 2500 |
| Google AI 概览 | @olostep/google-ai-overview-results | https://www.google.com/search?q={query} | 3 | 2500 |
| ChatGPT | @olostep/chatgpt-results | https://chatgpt.com/?q={query} | 5 | 2500 |
| Perplexity | @olostep/perplexity-results | https://www.perplexity.ai/?q={query} | 3 | 2500 |
| Gemini | @olostep/gemini-results | https://gemini.google.com/?q={query} | 3 | 2500 |
| Microsoft Copilot | @olostep/microsoft-copilot-results | https://copilot.microsoft.com/chats?q={query} | 3 | 1000 |
country 参数（ISO 3166-1 alpha-2）进行地理定位。国家覆盖范围因解析器而异——获取实时列表而不是硬编码：
curl "https://api.olostep.com/v1/countries?service=batches&parser=@olostep/google-aimode-results"
what is mitochondria）。当你需要广告、购物卡或产品模块时，使用商业提示（best wireless headphones under $200）——这些界面是意图检测的，当引擎不呈现它们时会被省略。
定价
这是我们为自助服务客户提供的公开定价。我们为企业客户提供更好的费率和批量折扣。我们还为专用平台和 LLM 引擎提供自定义连接器。通过 email 或 Slack 联系我们。1. 创建批处理
custom_id 在批处理中必须是唯一的。country 应用于每个项目。
from olostep import Olostep
from urllib.parse import quote_plus
client = Olostep(api_key="YOUR_API_KEY")
queries = [
"what is mitochondria",
"best wireless headphones under $200",
]
batch = client.batches.create(
urls=[
{
"custom_id": f"aimode-{i}",
"url": f"https://www.google.com/aimode?q={quote_plus(q)}",
}
for i, q in enumerate(queries, start=1)
],
parser="@olostep/google-aimode-results",
country="US",
)
print(batch.id, batch.status)
import Olostep from 'olostep'
const client = new Olostep({ apiKey: 'YOUR_API_KEY' })
const queries = [
'what is mitochondria',
'best wireless headphones under $200',
]
const batch = await client.batches.create(
queries.map((q, i) => ({
customId: `aimode-${i + 1}`,
url: `https://www.google.com/aimode?q=${encodeURIComponent(q)}`,
})),
{
parser: '@olostep/google-aimode-results',
country: 'US',
}
)
console.log(batch.id, batch.status)
curl -X POST "https://api.olostep.com/v1/batches" \
-H "Authorization: Bearer $OLOSTEP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"parser": { "id": "@olostep/google-aimode-results" },
"country": "US",
"items": [
{
"custom_id": "aimode-1",
"url": "https://www.google.com/aimode?q=what%20is%20mitochondria"
},
{
"custom_id": "aimode-2",
"url": "https://www.google.com/aimode?q=best%20wireless%20headphones%20under%20%24200"
}
]
}'
items 结构并交换 parser.id 以及每个 URL 中的主机。一个批处理 = 一个解析器。
处理时间大致恒定，无论批处理大小（通常为 5–8 分钟）。在创建时传递
webhook 以获取 batch.completed 而不是轮询。新账户限制为每批 100 项——联系 info@olostep.com 提高限制。2. 等待完成
轮询 GET /v1/batches/{batch_id} 直到status 为 completed，或处理 webhook。
import time
import requests
headers = {"Authorization": f"Bearer {API_KEY}"}
def wait_for_batch(batch_id):
while True:
info = requests.get(
f"https://api.olostep.com/v1/batches/{batch_id}",
headers=headers,
).json()
if info["status"] == "completed":
return info
time.sleep(15)
async function waitForBatch(batchId) {
while (true) {
const res = await fetch(`https://api.olostep.com/v1/batches/${batchId}`, {
headers: { Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}` },
})
const info = await res.json()
if (info.status === 'completed') return info
await new Promise((r) => setTimeout(r, 15000))
}
}
curl "https://api.olostep.com/v1/batches/batch_abc123" \
-H "Authorization: Bearer $OLOSTEP_API_KEY"
batch.items() / for await (const item of batch.items())，它们会阻塞直到批处理完成。
3. 检索 json_content
列出项目，然后为每个 retrieve_id 检索 JSON。GEO 负载是 json_content 内解析的对象（一个 JSON 字符串——解析它）。
import json
import requests
headers = {"Authorization": f"Bearer {API_KEY}"}
items = requests.get(
f"https://api.olostep.com/v1/batches/{batch_id}/items",
headers=headers,
).json()["items"]
for item in items:
payload = requests.get(
"https://api.olostep.com/v1/retrieve",
headers=headers,
params={"retrieve_id": item["retrieve_id"], "formats": "json"},
).json()
data = json.loads(payload["json_content"])
print(item["custom_id"], data.get("prompt"), len(data.get("sources") or []))
const itemsRes = await fetch(
`https://api.olostep.com/v1/batches/${batchId}/items`,
{ headers: { Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}` } }
)
const { items } = await itemsRes.json()
for (const item of items) {
const params = new URLSearchParams({
retrieve_id: item.retrieve_id,
formats: 'json',
})
const payload = await fetch(
`https://api.olostep.com/v1/retrieve?${params}`,
{ headers: { Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}` } }
).then((r) => r.json())
const data = JSON.parse(payload.json_content)
console.log(item.custom_id, data.prompt, (data.sources || []).length)
}
for item in batch.items():
content = item.retrieve(["json"])
print(item.custom_id, content.json_content)
status=failed。托管的 JSON 也可以在检索负载的 json_hosted_url 上使用大约 7 天。
你得到的内容
每个解析器返回answer_markdown。大多数还返回 prompt。其余的是引擎特定的。下面的简要概览来自实时 country=US 批处理。
这里列出的引擎是公共的 GEO 解析器。我们还在内部支持其他解析器和连接器，以及特定网站的自定义解析器——我们会根据请求分享这些。发送电子邮件至 info@olostep.com 或在 Slack 上联系我们。
- Google AI 模式
- ChatGPT
- Perplexity
- Google AI 概览
- Gemini
- Microsoft Copilot
引文在
sources 中（当内联引用时 cited: true）。结构化部分在 text_blocks 中（text、heading、list、table）。当 Google 显示赞助卡时，它们在 ads 中——一个实时耳机查询返回了来源和比较表，但省略了 ads。空字段被剥离，不作为 [] 返回。{
"answer_markdown": "寻找 200 美元以下最佳无线头戴式或耳罩式耳机时...",
"sources": [
{
"url": "https://www.reddit.com/r/HeadphoneAdvice/comments/173hvu2/best_wireless_headphones_for_under_200_dollars/",
"title": "200 美元以下最佳无线耳机：r/HeadphoneAdvice",
"description": "根据 Reddit 用户，Sennheiser Accentum 耳机是一个不错的选择...",
"domain": "https://www.reddit.com",
"cited": false
}
],
"text_blocks": [
{ "type": "text", "snippet": "寻找 200 美元以下最佳无线头戴式或耳罩式耳机时..." },
{
"type": "table",
"snippet": "型号 | 最佳用途 | 关键特性 | 价格范围",
"data": {
"headers": ["型号", "最佳用途", "关键特性", "价格范围"],
"rows": [
["Anker Soundcore Space Q45", "整体价值 & ANC", "强大的自适应 ANC，50 小时电池寿命", "~$100 - $150"]
]
}
}
]
}
内联芯片是
inline_references。来源抽屉是 sources。购物是 products。赞助品牌块是 ads（brand + cards）。空模块是 []。network_search_calls 是网络搜索跟踪。{
"url": "https://chatgpt.com/?q=best%20wireless%20headphones%20under%20%24200",
"prompt": "best wireless headphones under $200",
"answer_markdown": "如果你指的是 **带有 ANC 的无线头戴式耳机**...",
"inline_references": [
{
"url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
"text": "2026 年 200 美元以下最佳耳机 - RTINGS.com",
"position": 1
}
],
"sources": [
{
"url": "https://www.tomsguide.com/us/best-headphones-deals,news-28645.html",
"title": "2026 年 8 月最佳耳机交易",
"snippet": "2026 年 8 月耳机交易汇总...",
"cited": false,
"date_published": "2026-08-19T16:18:38.000Z",
"attribution": "www.tomsguide.com"
}
],
"ads": [
{
"brand": { "name": "Razer", "url": "https://www.razer.com/" },
"cards": [
{
"title": "Razer BlackShark V3 Pro",
"body": "专业人士赞扬其无与伦比的清晰度...",
"url": "https://www.razer.com/gaming-headsets/razer-blackshark-v3-pro?utm_source=chatgpt&...",
"image": "https://bzrcdn.openai.com/fe8bef58c7129858.jpg"
}
]
}
],
"products": [
{
"title": "Soundcore Space Q45",
"price": 139.99,
"currency": "$",
"vendors": [
{
"price": 139.99,
"currency": "$",
"website": "Best Buy",
"link": "https://www.bestbuy.com/product/soundcore-by-anker-space-q45-...?utm_source=chatgpt.com"
}
]
}
],
"locations": [],
"web_searched": true,
"network_search_calls": {
"search_triggered": true,
"model_slug": "auto",
"search_queries": [
{ "query": "best wireless headphones under $200 2026 Sony WH-CH720N Soundcore Space Q45...", "type": "model_query" }
]
}
}
shopping_cards、videos、images、hotels 和 places 是空数组，当该模块未显示时。search_model_queries 是 Perplexity 实际搜索的内容。{
"url": "https://www.perplexity.ai/search/53051455-01ac-48a2-8aa7-45e518588af0",
"prompt": "best wireless headphones under $200",
"answer_markdown": "* Anker Soundcore Space Q45 Wireless...",
"sources": [
{
"position": 1,
"label": "2026 年 200 美元以下最佳耳机",
"url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
"description": "",
"domain": "www.rtings.com",
"date": ""
}
],
"related_queries": [
"200 美元以下最佳预算无线耳机，音质"
],
"shopping_cards": [],
"videos": [],
"images": [],
"hotels": [],
"places": [],
"search_model_queries": [
{ "query": "best wireless headphones under $200", "engine": "web", "limit": 8 }
],
"model": "perplexity",
"web_searched": true
}
text_blocks 是分段和列表的概览。sources 是 AIO 引用。organic_results 是经典的 SERP 在下方，当存在时。{
"url": "https://www.google.com/search?q=what+is+mitochondria&gl=us",
"prompt": "what is mitochondria",
"answer_markdown": "线粒体\n\n线粒体是膜结合的细胞器...",
"sources": [
{
"title": "线粒体",
"url": "https://www.youtube.com/watch?v=sl6RXHnAMVs&t=7",
"source": "YouTube",
"index": 1
}
],
"text_blocks": [
{ "type": "paragraph", "snippet": "线粒体\n\n线粒体是膜结合的细胞器..." }
],
"organic_results": [
{
"position": 1,
"title": "线粒体",
"link": "https://www.genome.gov/genetics-glossary/Mitochondria",
"snippet": "线粒体是膜结合的细胞器..."
}
]
}
{
"url": "https://gemini.google.com/app/d11cddf049763b9b",
"prompt": "best wireless headphones under $200",
"answer_markdown": "寻找 200 美元以下的优秀无线耳机...",
"sources": [
{
"position": 1,
"label": "200 美元以下最佳降噪耳机（测试超过 50 个！）",
"url": "https://recordingnow.com/blog/best-budget-wireless-headphones/",
"description": "Sony WH-CH720N 是最轻的全尺寸...",
"confidence_level": 9
}
],
"links_attached": true,
"model": "gemini"
}
sources[].position 是 answer_markdown 中的字符偏移，而不是排名。cited 表示来源是否在答案中附加。{
"url": "https://copilot.microsoft.com/chats?q=best%20wireless%20headphones%20under%20%24200",
"prompt": "best wireless headphones under $200",
"answer_markdown": "**2026 年 200 美元以下最佳无线耳机是 Sony WH-CH720N...",
"sources": [
{
"url": "https://progressiveradionetwork.com/best-wireless-headphones-under-200-dollars/",
"title": "10 款 200 美元以下最佳无线耳机（2026 年 8 月）测试",
"position": 1124,
"icon_url": "https://services.bingapis.com/favicon?url=progressiveradionetwork.com",
"cited": true
}
]
}