AI 検索エンジンを追跡

/batches と GEO/AEO (生成エンジン最適化 / 回答エンジン最適化) パーサーを使用して、AI 検索エンジンに大規模にクエリを送り、構造化された JSON を取得します: 回答、引用、広告、ショッピングカード、商品モジュールなどの商業的な要素。このページでは、/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) を使用します。これらの要素は意図検出され、エンジンがそれらを表示しない場合は省略されます。

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 のホストを交換します。1 バッチ = 1 パーサーです。

処理時間はバッチサイズに関係なくほぼ一定です (通常 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"

Python と Node SDK はあなたの代わりに待機できます: 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)

失敗したアイテムは別々にリストされます — GET /v1/batches/{batch_id}/items で status=failed を渡します。ホストされた JSON は、取得ペイロードの json_hosted_url で約 7 日間利用可能です。

返される内容

すべてのパーサーは answer_markdown を返します。ほとんどは prompt も返します。残りはエンジン固有です。以下の簡潔なプレビューは、country=US バッチからのものです。

ここにリストされているエンジンは、公開されている GEO パーサーです。私たちは内部で追加のパーサーやコネクタもサポートしており、特定のサイト用のカスタムパーサーも提供しています — リクエストに応じてそれらを共有します。info@olostep.com にメールするか、Slack でご連絡ください。

引用は sources にあります (インラインで参照されると cited: true)。構造化されたセクションは text_blocks にあります (text, heading, list, table)。Google が表示する場合、スポンサー付きカードは ads にあります — ライブのヘッドフォンのクエリはソースと比較表を返しましたが、ads は省略されました。空のフィールドは削除され、[] として返されません。

{
  "answer_markdown": "When looking for the best wireless over-ear or on-ear headphones under $200...",
  "sources": [
    {
      "url": "https://www.reddit.com/r/HeadphoneAdvice/comments/173hvu2/best_wireless_headphones_for_under_200_dollars/",
      "title": "Best wireless headphones for under 200 dollars : r/HeadphoneAdvice",
      "description": "According to a Reddit user, the Sennheiser Accentum headphones are a good option...",
      "domain": "https://www.reddit.com",
      "cited": false
    }
  ],
  "text_blocks": [
    { "type": "text", "snippet": "When looking for the best wireless over-ear or on-ear headphones under $200..." },
    {
      "type": "table",
      "snippet": "Model | Best For | Key Features | Price Range",
      "data": {
        "headers": ["Model", "Best For", "Key Features", "Price Range"],
        "rows": [
          ["Anker Soundcore Space Q45", "Overall Value & ANC", "Strong adaptive ANC, 50-hour battery life", "~$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": "If you mean **over-ear wireless headphones with ANC**...",
  "inline_references": [
    {
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "text": "The 5 Best Headphones Under $200 of 2026 - RTINGS.com",
      "position": 1
    }
  ],
  "sources": [
    {
      "url": "https://www.tomsguide.com/us/best-headphones-deals,news-28645.html",
      "title": "Best headphone deals for August 2026",
      "snippet": "This August 2026 headphone deal roundup...",
      "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": "Pros swear by its unrivaled clarity...",
          "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": "The 5 Best Headphones Under $200 of 2026",
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "description": "",
      "domain": "www.rtings.com",
      "date": ""
    }
  ],
  "related_queries": [
    "best budget wireless headphones under 200 dollars for sound quality"
  ],
  "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": "mitochondria\n\nMitochondria are membrane-bound organelles...",
  "sources": [
    {
      "title": "The Mitochondria",
      "url": "https://www.youtube.com/watch?v=sl6RXHnAMVs&t=7",
      "source": "YouTube",
      "index": 1
    }
  ],
  "text_blocks": [
    { "type": "paragraph", "snippet": "mitochondria\n\nMitochondria are membrane-bound organelles..." }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "Mitochondria",
      "link": "https://www.genome.gov/genetics-glossary/Mitochondria",
      "snippet": "Mitochondria are membrane-bound cell organelles..."
    }
  ]
}

{
  "url": "https://gemini.google.com/app/d11cddf049763b9b",
  "prompt": "best wireless headphones under $200",
  "answer_markdown": "Finding great wireless headphones under $200...",
  "sources": [
    {
      "position": 1,
      "label": "Best Noise Cancelling Headphones under $200 (50+ Tested!)",
      "url": "https://recordingnow.com/blog/best-budget-wireless-headphones/",
      "description": "The Sony WH-CH720N is the LIGHTEST full-sized...",
      "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": "**The best wireless headphones under $200 in 2026 are the Sony WH-CH720N...",
  "sources": [
    {
      "url": "https://progressiveradionetwork.com/best-wireless-headphones-under-200-dollars/",
      "title": "10 Best Wireless Headphones Under 200$ (August 2026) Tested",
      "position": 1124,
      "icon_url": "https://services.bingapis.com/favicon?url=progressiveradionetwork.com",
      "cited": true
    }
  ]
}

例

AI 検索エンジンを追跡

エンジン

1. バッチを作成

2. 完了を待つ

3. `json_content` を取得

返される内容

関連

​エンジン

​1. バッチを作成

​2. 完了を待つ

​3. json_content を取得

​返される内容

​関連

エンジン

1. バッチを作成

2. 完了を待つ

3. `json_content` を取得

返される内容

関連