Traccia i motori di ricerca AI

Usa /batches insieme a un parser GEO/AEO (Generative Engine Optimization / Answer Engine Optimization) per interrogare un motore di ricerca AI su larga scala e ottenere un JSON strutturato: la risposta, le citazioni e le superfici commerciali come annunci, schede di shopping e moduli di prodotto. Questa pagina copre come chiamare /v1/batches e fornisce brevi anteprime del JSON che ricevi indietro.

Motori

Ogni motore necessita del proprio ID parser e modello URL. Passa il parser una volta a livello di batch. Codifica la query nell’URL.

Motore	Parser	Modello URL	Crediti	Max elementi
Google AI Mode	`@olostep/google-aimode-results`	`https://www.google.com/aimode?q={query}`	3	2500
Google AI Overview	`@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

Tutti e sei supportano il targeting geografico tramite il parametro country del batch (ISO 3166-1 alpha-2). La copertura dei paesi varia a seconda del parser — recupera la lista aggiornata piuttosto che codificarla:

curl "https://api.olostep.com/v1/countries?service=batches&parser=@olostep/google-aimode-results"

Usa un prompt informativo (what is mitochondria) quando ti interessano le citazioni. Usa un prompt commerciale (best wireless headphones under $200) quando hai bisogno di annunci, schede di shopping o moduli di prodotto — quelle superfici sono rilevate in base all’intento e omesse quando il motore non le visualizza.

1. Crea il batch

custom_id deve essere unico all’interno del batch. country è applicato a ogni elemento.

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"
      }
    ]
  }'

Per puntare a un motore diverso, mantieni la stessa struttura items e sostituisci parser.id più l’host in ogni URL. Un batch = un parser.

Il tempo di elaborazione è approssimativamente costante indipendentemente dalla dimensione del batch (tipicamente 5–8 minuti). Passa webhook alla creazione per ottenere batch.completed invece di fare polling. I nuovi account sono limitati a 100 elementi per batch — contatta info@olostep.com per aumentare il limite.

2. Attendi il completamento

Fai polling su GET /v1/batches/{batch_id} fino a quando status è completed, o gestisci il 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"

Gli SDK Python e Node possono attendere per te: itera batch.items() / for await (const item of batch.items()) e bloccano fino a quando il batch non è completato.

3. Recupera `json_content`

Elenca gli elementi, quindi recupera il JSON per ogni retrieve_id. Il payload GEO è l’oggetto analizzato all’interno di json_content (una stringa JSON — analizzala).

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)

Gli elementi falliti sono elencati separatamente — passa status=failed su GET /v1/batches/{batch_id}/items. Il JSON ospitato è anche disponibile su json_hosted_url nel payload di recupero per circa 7 giorni.

Cosa ottieni indietro

Ogni parser restituisce answer_markdown. La maggior parte restituisce anche prompt. Il resto è specifico del motore. Le anteprime compatte di seguito provengono da batch live country=US.

I motori elencati qui sono i parser GEO pubblici. Supportiamo anche parser e connettori aggiuntivi internamente, oltre a parser personalizzati per siti specifici — li condividiamo su richiesta. Invia un’email a info@olostep.com o contattaci su Slack.

Le citazioni sono in sources (cited: true quando sono referenziate inline). Le sezioni strutturate sono in text_blocks (text, heading, list, table). Le schede sponsorizzate sono in ads quando Google le mostra — una query live sulle cuffie ha restituito fonti e una tabella di confronto ma ha omesso ads. I campi vuoti sono eliminati, non restituiti come [].

{
  "answer_markdown": "Quando cerchi le migliori cuffie wireless over-ear o on-ear sotto i $200...",
  "sources": [
    {
      "url": "https://www.reddit.com/r/HeadphoneAdvice/comments/173hvu2/best_wireless_headphones_for_under_200_dollars/",
      "title": "Migliori cuffie wireless sotto i 200 dollari: r/HeadphoneAdvice",
      "description": "Secondo un utente di Reddit, le cuffie Sennheiser Accentum sono una buona opzione...",
      "domain": "https://www.reddit.com",
      "cited": false
    }
  ],
  "text_blocks": [
    { "type": "text", "snippet": "Quando cerchi le migliori cuffie wireless over-ear o on-ear sotto i $200..." },
    {
      "type": "table",
      "snippet": "Modello | Migliore per | Caratteristiche principali | Fascia di prezzo",
      "data": {
        "headers": ["Modello", "Migliore per", "Caratteristiche principali", "Fascia di prezzo"],
        "rows": [
          ["Anker Soundcore Space Q45", "Valore complessivo & ANC", "Forte ANC adattivo, durata della batteria di 50 ore", "~$100 - $150"]
        ]
      }
    }
  ]
}

I chip inline sono inline_references. Il cassetto delle fonti è sources. Lo shopping è products. I blocchi di marca sponsorizzati sono ads (brand + cards). I moduli vuoti sono []. network_search_calls è la traccia della ricerca web.

{
  "url": "https://chatgpt.com/?q=best%20wireless%20headphones%20under%20%24200",
  "prompt": "migliori cuffie wireless sotto i $200",
  "answer_markdown": "Se intendi **cuffie wireless over-ear con ANC**...",
  "inline_references": [
    {
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "text": "Le 5 migliori cuffie sotto i $200 del 2026 - RTINGS.com",
      "position": 1
    }
  ],
  "sources": [
    {
      "url": "https://www.tomsguide.com/us/best-headphones-deals,news-28645.html",
      "title": "Migliori offerte di cuffie per agosto 2026",
      "snippet": "Questo riepilogo delle offerte di cuffie di agosto 2026...",
      "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": "I professionisti giurano sulla sua chiarezza impareggiabile...",
          "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": "migliori cuffie wireless sotto i $200 2026 Sony WH-CH720N Soundcore Space Q45...", "type": "model_query" }
    ]
  }
}

shopping_cards, videos, images, hotels, e places sono array vuoti quando quel modulo non è stato mostrato. search_model_queries è ciò che Perplexity ha effettivamente cercato.

{
  "url": "https://www.perplexity.ai/search/53051455-01ac-48a2-8aa7-45e518588af0",
  "prompt": "migliori cuffie wireless sotto i $200",
  "answer_markdown": "*   Anker Soundcore Space Q45 Wireless...",
  "sources": [
    {
      "position": 1,
      "label": "Le 5 migliori cuffie sotto i $200 del 2026",
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "description": "",
      "domain": "www.rtings.com",
      "date": ""
    }
  ],
  "related_queries": [
    "migliori cuffie wireless economiche sotto i 200 dollari per qualità del suono"
  ],
  "shopping_cards": [],
  "videos": [],
  "images": [],
  "hotels": [],
  "places": [],
  "search_model_queries": [
    { "query": "migliori cuffie wireless sotto i $200", "engine": "web", "limit": 8 }
  ],
  "model": "perplexity",
  "web_searched": true
}

text_blocks è l’overview suddivisa in paragrafi e liste. sources sono le citazioni AIO. organic_results è il classico SERP sottostante, quando presente.

{
  "url": "https://www.google.com/search?q=what+is+mitochondria&gl=us",
  "prompt": "cos'è il mitocondrio",
  "answer_markdown": "mitocondri\n\nI mitocondri sono organelli legati alla membrana...",
  "sources": [
    {
      "title": "Il Mitocondrio",
      "url": "https://www.youtube.com/watch?v=sl6RXHnAMVs&t=7",
      "source": "YouTube",
      "index": 1
    }
  ],
  "text_blocks": [
    { "type": "paragraph", "snippet": "mitocondri\n\nI mitocondri sono organelli legati alla membrana..." }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "Mitocondri",
      "link": "https://www.genome.gov/genetics-glossary/Mitochondria",
      "snippet": "I mitocondri sono organelli cellulari legati alla membrana..."
    }
  ]
}

{
  "url": "https://gemini.google.com/app/d11cddf049763b9b",
  "prompt": "migliori cuffie wireless sotto i $200",
  "answer_markdown": "Trovare ottime cuffie wireless sotto i $200...",
  "sources": [
    {
      "position": 1,
      "label": "Migliori Cuffie con Cancellazione del Rumore sotto i $200 (50+ Testate!)",
      "url": "https://recordingnow.com/blog/best-budget-wireless-headphones/",
      "description": "Le Sony WH-CH720N sono le più leggere a grandezza naturale...",
      "confidence_level": 9
    }
  ],
  "links_attached": true,
  "model": "gemini"
}

sources[].position è un offset di carattere in answer_markdown, non un rango. cited indica se la fonte è allegata nella risposta.

{
  "url": "https://copilot.microsoft.com/chats?q=best%20wireless%20headphones%20under%20%24200",
  "prompt": "migliori cuffie wireless sotto i $200",
  "answer_markdown": "**Le migliori cuffie wireless sotto i $200 nel 2026 sono le Sony WH-CH720N...",
  "sources": [
    {
      "url": "https://progressiveradionetwork.com/best-wireless-headphones-under-200-dollars/",
      "title": "10 Migliori Cuffie Wireless Sotto i 200$ (Agosto 2026) Testate",
      "position": 1124,
      "icon_url": "https://services.bingapis.com/favicon?url=progressiveradionetwork.com",
      "cited": true
    }
  ]
}

Esempi

Traccia i motori di ricerca AI

Motori

1. Crea il batch

2. Attendi il completamento

3. Recupera `json_content`

Cosa ottieni indietro

Correlati

​Motori

​1. Crea il batch

​2. Attendi il completamento

​3. Recupera json_content

​Cosa ottieni indietro

​Correlati

Motori

1. Crea il batch

2. Attendi il completamento

3. Recupera `json_content`

Cosa ottieni indietro

Correlati