Suivre les moteurs de recherche AI

Utilisez /batches plus un parseur GEO/AEO (Optimisation de Moteur Génératif / Optimisation de Moteur de Réponse) pour interroger un moteur de recherche AI à grande échelle et obtenir un JSON structuré en retour : la réponse, les citations, et les surfaces commerciales telles que les publicités, les cartes d’achat et les modules de produits. Cette page couvre comment appeler /v1/batches et des aperçus compacts du JSON que vous recevez.

Moteurs

Chaque moteur nécessite son propre ID de parseur et modèle d’URL. Passez le parseur une fois au niveau du batch. Encodez la requête dans l’URL.

Moteur	Parseur	Modèle d’URL	Crédits	Articles max
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

Les six prennent en charge le ciblage géographique via le paramètre country du batch (ISO 3166-1 alpha-2). La couverture par pays diffère selon le parseur — récupérez la liste en direct plutôt que de la coder en dur :

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

Utilisez une invite informative (qu'est-ce que les mitochondries) lorsque vous vous souciez des citations. Utilisez une invite commerciale (meilleurs écouteurs sans fil à moins de 200 $) lorsque vous avez besoin de publicités, de cartes d’achat ou de modules de produits — ces surfaces sont détectées par intention et omises lorsque le moteur ne les rend pas.

1. Créer le batch

custom_id doit être unique au sein du batch. country est appliqué à chaque élément.

from olostep import Olostep
from urllib.parse import quote_plus

client = Olostep(api_key="YOUR_API_KEY")

queries = [
    "qu'est-ce que les mitochondries",
    "meilleurs écouteurs sans fil à moins de 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 = [
  'qu'est-ce que les mitochondries',
  'meilleurs écouteurs sans fil à moins de 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=qu%27est-ce%20que%20les%20mitochondries"
      },
      {
        "custom_id": "aimode-2",
        "url": "https://www.google.com/aimode?q=meilleurs%20%C3%A9couteurs%20sans%20fil%20%C3%A0%20moins%20de%20200%20%24"
      }
    ]
  }'

Pour cibler un moteur différent, gardez la même structure items et échangez parser.id plus l’hôte dans chaque URL. Un batch = un parseur.

Le temps de traitement est à peu près constant, quelle que soit la taille du batch (typiquement 5–8 minutes). Passez webhook lors de la création pour obtenir batch.completed au lieu de faire un sondage. Les nouveaux comptes sont limités à 100 articles par batch — contactez info@olostep.com pour augmenter cette limite.

2. Attendre la complétion

Sondez GET /v1/batches/{batch_id} jusqu’à ce que status soit completed, ou gérez le 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"

Les SDK Python et Node peuvent attendre pour vous : itérez batch.items() / for await (const item of batch.items()) et ils bloquent jusqu’à ce que le batch soit terminé.

3. Récupérer `json_content`

Listez les éléments, puis récupérez le JSON pour chaque retrieve_id. La charge utile GEO est l’objet analysé à l’intérieur de json_content (une chaîne JSON — analysez-la).

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)

Les éléments échoués sont listés séparément — passez status=failed sur GET /v1/batches/{batch_id}/items. Le JSON hébergé est également disponible à json_hosted_url sur la charge utile de récupération pendant environ 7 jours.

Ce que vous recevez

Chaque parseur renvoie answer_markdown. La plupart renvoient également prompt. Le reste est spécifique au moteur. Les aperçus compacts ci-dessous proviennent de batches en direct country=US.

Les moteurs listés ici sont les parseurs GEO publics. Nous prenons également en charge des parseurs et connecteurs supplémentaires en interne, ainsi que des parseurs personnalisés pour des sites spécifiques — nous les partageons sur demande. Envoyez un email à info@olostep.com ou contactez-nous sur Slack.

Les citations sont dans sources (cited: true lorsqu’elles sont référencées en ligne). Les sections structurées sont dans text_blocks (text, heading, list, table). Les cartes sponsorisées sont dans ads lorsque Google les affiche — une requête en direct sur les écouteurs a renvoyé des sources et un tableau comparatif mais a omis ads. Les champs vides sont supprimés, non renvoyés comme [].

{
  "answer_markdown": "Lors de la recherche des meilleurs écouteurs sans fil supra-auriculaires ou circum-auriculaires à moins de 200 $...",
  "sources": [
    {
      "url": "https://www.reddit.com/r/HeadphoneAdvice/comments/173hvu2/best_wireless_headphones_for_under_200_dollars/",
      "title": "Meilleurs écouteurs sans fil pour moins de 200 dollars : r/HeadphoneAdvice",
      "description": "Selon un utilisateur de Reddit, les écouteurs Sennheiser Accentum sont une bonne option...",
      "domain": "https://www.reddit.com",
      "cited": false
    }
  ],
  "text_blocks": [
    { "type": "text", "snippet": "Lors de la recherche des meilleurs écouteurs sans fil supra-auriculaires ou circum-auriculaires à moins de 200 $..." },
    {
      "type": "table",
      "snippet": "Modèle | Meilleur pour | Caractéristiques clés | Gamme de prix",
      "data": {
        "headers": ["Modèle", "Meilleur pour", "Caractéristiques clés", "Gamme de prix"],
        "rows": [
          ["Anker Soundcore Space Q45", "Valeur globale & ANC", "ANC adaptatif puissant, autonomie de 50 heures", "~100 $ - 150 $"]
        ]
      }
    }
  ]
}

Les puces en ligne sont inline_references. Le tiroir des sources est sources. Les achats sont products. Les blocs de marque sponsorisés sont ads (brand + cards). Les modules vides sont []. network_search_calls est la trace de recherche web.

{
  "url": "https://chatgpt.com/?q=meilleurs%20%C3%A9couteurs%20sans%20fil%20%C3%A0%20moins%20de%20200%20%24",
  "prompt": "meilleurs écouteurs sans fil à moins de 200 $",
  "answer_markdown": "Si vous voulez dire **écouteurs sans fil supra-auriculaires avec ANC**...",
  "inline_references": [
    {
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "text": "Les 5 meilleurs écouteurs à moins de 200 $ de 2026 - RTINGS.com",
      "position": 1
    }
  ],
  "sources": [
    {
      "url": "https://www.tomsguide.com/us/best-headphones-deals,news-28645.html",
      "title": "Meilleures offres d'écouteurs pour août 2026",
      "snippet": "Ce récapitulatif des offres d'écouteurs d'août 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": "Les pros jurent par sa clarté inégalée...",
          "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": "meilleurs écouteurs sans fil à moins de 200 $ 2026 Sony WH-CH720N Soundcore Space Q45...", "type": "model_query" }
    ]
  }
}

shopping_cards, videos, images, hotels, et places sont des tableaux vides lorsque ce module n’a pas été affiché. search_model_queries est ce que Perplexity a réellement recherché.

{
  "url": "https://www.perplexity.ai/search/53051455-01ac-48a2-8aa7-45e518588af0",
  "prompt": "meilleurs écouteurs sans fil à moins de 200 $",
  "answer_markdown": "*   Anker Soundcore Space Q45 Wireless...",
  "sources": [
    {
      "position": 1,
      "label": "Les 5 meilleurs écouteurs à moins de 200 $ de 2026",
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "description": "",
      "domain": "www.rtings.com",
      "date": ""
    }
  ],
  "related_queries": [
    "meilleurs écouteurs sans fil à petit budget à moins de 200 dollars pour la qualité sonore"
  ],
  "shopping_cards": [],
  "videos": [],
  "images": [],
  "hotels": [],
  "places": [],
  "search_model_queries": [
    { "query": "meilleurs écouteurs sans fil à moins de 200 $", "engine": "web", "limit": 8 }
  ],
  "model": "perplexity",
  "web_searched": true
}

text_blocks est l’aperçu divisé en paragraphes et listes. sources sont les citations AIO. organic_results est le SERP classique en dessous, lorsqu’il est présent.

{
  "url": "https://www.google.com/search?q=qu%27est-ce+que+les+mitochondries&gl=us",
  "prompt": "qu'est-ce que les mitochondries",
  "answer_markdown": "mitochondries\n\nLes mitochondries sont des organites liés à la membrane...",
  "sources": [
    {
      "title": "Les Mitochondries",
      "url": "https://www.youtube.com/watch?v=sl6RXHnAMVs&t=7",
      "source": "YouTube",
      "index": 1
    }
  ],
  "text_blocks": [
    { "type": "paragraph", "snippet": "mitochondries\n\nLes mitochondries sont des organites liés à la membrane..." }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "Mitochondries",
      "link": "https://www.genome.gov/genetics-glossary/Mitochondria",
      "snippet": "Les mitochondries sont des organites cellulaires liés à la membrane..."
    }
  ]
}

{
  "url": "https://gemini.google.com/app/d11cddf049763b9b",
  "prompt": "meilleurs écouteurs sans fil à moins de 200 $",
  "answer_markdown": "Trouver de superbes écouteurs sans fil à moins de 200 $...",
  "sources": [
    {
      "position": 1,
      "label": "Meilleurs écouteurs à réduction de bruit à moins de 200 $ (50+ testés !)",
      "url": "https://recordingnow.com/blog/best-budget-wireless-headphones/",
      "description": "Le Sony WH-CH720N est le plus léger de taille réelle...",
      "confidence_level": 9
    }
  ],
  "links_attached": true,
  "model": "gemini"
}

sources[].position est un décalage de caractère dans answer_markdown, pas un rang. cited indique si la source est attachée dans la réponse.

{
  "url": "https://copilot.microsoft.com/chats?q=meilleurs%20%C3%A9couteurs%20sans%20fil%20%C3%A0%20moins%20de%20200%20%24",
  "prompt": "meilleurs écouteurs sans fil à moins de 200 $",
  "answer_markdown": "**Les meilleurs écouteurs sans fil à moins de 200 $ en 2026 sont les Sony WH-CH720N...",
  "sources": [
    {
      "url": "https://progressiveradionetwork.com/best-wireless-headphones-under-200-dollars/",
      "title": "10 meilleurs écouteurs sans fil à moins de 200 $ (août 2026) testés",
      "position": 1124,
      "icon_url": "https://services.bingapis.com/favicon?url=progressiveradionetwork.com",
      "cited": true
    }
  ]
}

Exemples

Suivre les moteurs de recherche AI

Moteurs

1. Créer le batch

2. Attendre la complétion

3. Récupérer `json_content`

Ce que vous recevez

Connexes

​Moteurs

​1. Créer le batch

​2. Attendre la complétion

​3. Récupérer json_content

​Ce que vous recevez

​Connexes

Moteurs

1. Créer le batch

2. Attendre la complétion

3. Récupérer `json_content`

Ce que vous recevez

Connexes