Comment utiliser WebScrapingAPI : guide de l'API de scraping et de Web MCP

L'API Scraper est un point de terminaison REST qui prend une URL cible et renvoie la page au format HTML, JSON ou sous forme de champs sélectionnés. WebScrapingAPI gère les proxys, la rotation, la gestion des accès, les tentatives de reconnexion et le rendu JavaScript (en option). Utilisez-la lorsque vous connaissez déjà les URL dont vous avez besoin et que vous souhaitez obtenir le contenu des pages sans avoir à gérer d'infrastructure de scraping.

Votre application fournit l’URL cible et tout contexte de requête, tel qu’un pays ou un format de sortie. WebScrapingAPI gère la couche d’accès derrière cette requête : routage et rotation des proxys, stratégies de gestion des accès, tentatives de connexion internes vers la cible et utilisation d’un navigateur lorsque vous demandez un rendu. Le résultat renvoyé est le corps de la page, une enveloppe JSON contenant des métadonnées, un DOM JSON ou uniquement les champs que vous avez sélectionnés. Lorsqu’une requête ne peut être menée à bien, vous recevez une erreur explicite et documentée au lieu d’un contenu erroné renvoyé en silence.

Tout ce qui se trouve en dehors de cette couche reste de votre ressort : sources, objectif, analyse, validation et stockage. L’API se charge des tâches liées au proxy et au navigateur, mais pas du traitement en amont.

Chaque forfait, y compris la version d’essai, inclut le rendu JavaScript, le ciblage par pays dans toutes les zones géographiques et la rotation des proxys avec gestion des accès. Les forfaits se distinguent par le volume de requêtes, la concurrence et l’assistance, et non par les fonctionnalités.

Vous vous demandez encore si une API gérée vous convient ? Découvrez les avantages et les inconvénients liés à l’utilisation d’une API de scraping plutôt que de votre propre pile technologique. Si vous avez besoin de résultats de recherche, de clics et de temps d’attente sur une page, ou d’enregistrements structurés plutôt que de pages, passez directement au choix entre les cinq API Web Access.

Créez un compte, copiez votre clé API depuis l’onglet « Web Scraping API » du tableau de bord, puis enregistrez-la dans une variable d’environnement. Envoyez ensuite une requête GET à https://api.webscrapingapi.com/v2 avec la clé api_key et une URL encodée. Laissez votre bibliothèque HTTP s’occuper de l’encodage des paramètres, et n’appelez jamais l’API depuis le code d’un navigateur.

1. Inscrivez-vous. Créez un compte WebScrapingAPI et confirmez-le. La version d’essai vous donne droit à 5 000 requêtes.
2. Copiez votre clé. Dans le tableau de bord, ouvrez l'onglet « Web Scraping API » dans le panneau de gauche et copiez votre clé API.
3. Conservez-la comme une valeur secrète. Placez la clé dans une variable d’environnement sur le serveur qui effectuera les appels, comme indiqué ci-dessous.
4. Envoyez la requête. Utilisez l’un des exemples ci-dessous.

export WSA_API_KEY=...   # paste your key here, never into code

Les clés doivent être conservées dans des secrets côté serveur, jamais dans le code du navigateur, les applications mobiles, les dépôts publics, les journaux, les captures d’écran ou les carnets de notes partagés. Toute personne disposant de la clé peut utiliser les requêtes de votre forfait.

curl

curl --get "https://api.webscrapingapi.com/v2" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "render_js=1" \
  --data-urlencode "country=us"

--get avec --data-urlencode indique à curl de placer chaque paramètre dans la chaîne de requête et de l'encoder en pourcentage pour vous.

Python (Python 3 avec pip install requests)

Ce petit client sert de base au reste du guide. Il lit la clé à partir de WSA_API_KEY, laisse Requests encoder la chaîne de requête via params= (voir le guide de démarrage rapide de Requests), puis ne réessaie que les erreurs qui méritent d’être réessayées.

"""Minimal Scraper API client: env-var key, safe retries, optional JSON envelope.

Usage:
  export WSA_API_KEY=...            # never hardcode the key
  python wsa_scrape.py https://example.com
  python wsa_scrape.py https://example.com --render --country us --json
  python wsa_scrape.py https://example.com --dry-run   # print the request, no call
"""
import argparse
import json
import os
import sys
import time

import requests

ENDPOINT = "https://api.webscrapingapi.com/v2"
RETRYABLE = {429, 500, 503}          # back off and retry
FINAL = {400, 401, 403, 406}         # fix the request or the account; do not retry


def build_params(url, render=False, country=None, json_response=False, extract_rules=None):
    params = {"url": url}
    if render:
        params["render_js"] = "1"
    if country:
        params["country"] = country.lower()
    if json_response:
        params["json_response"] = "1"
    if extract_rules:
        # The API expects a JSON-stringified object; requests URL-encodes it.
        params["extract_rules"] = json.dumps(extract_rules, separators=(",", ":"))
    return params


def scrape(url, api_key, max_attempts=4, **opts):
    params = {"api_key": api_key, **build_params(url, **opts)}
    for attempt in range(1, max_attempts + 1):
        resp = requests.get(ENDPOINT, params=params, timeout=130)
        usage = {k: v for k, v in resp.headers.items() if k.lower().startswith("wsa-")}
        if resp.ok:
            return resp, usage
        if resp.status_code in FINAL:
            raise SystemExit(f"{resp.status_code}: {resp.text[:300]}")
        if resp.status_code == 422 and not opts.get("render"):
            # Scrape accepted but not completed (e.g. a challenge page). One rendered retry.
            opts["render"] = True
            params = {"api_key": api_key, **build_params(url, **opts)}
            continue
        if resp.status_code in RETRYABLE or resp.status_code == 422:
            time.sleep(min(2 ** attempt, 30))
            continue
        raise SystemExit(f"Unexpected {resp.status_code}: {resp.text[:300]}")
    raise SystemExit(f"Gave up after {max_attempts} attempts")


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("url")
    ap.add_argument("--render", action="store_true")
    ap.add_argument("--country")
    ap.add_argument("--json", dest="json_response", action="store_true")
    ap.add_argument("--dry-run", action="store_true")
    a = ap.parse_args()
    opts = dict(render=a.render, country=a.country, json_response=a.json_response)

    if a.dry_run:
        prepared = requests.Request("GET", ENDPOINT,
                                    params={"api_key": "REDACTED", **build_params(a.url, **opts)}).prepare()
        print(prepared.url)
        return

    api_key = os.environ.get("WSA_API_KEY")
    if not api_key:
        sys.exit("Set WSA_API_KEY first (dashboard -> Web Scraping API tab).")

    resp, usage = scrape(a.url, api_key, **opts)
    print("status:", resp.status_code)
    print("usage headers:", usage)
    if a.json_response:
        env = resp.json()
        print("initial-status-code:", env.get("initial-status-code"), "cost:", env.get("cost"), "type:", env.get("type"))
        print(env.get("body", "")[:300])
    else:
        print(resp.text[:300])


if __name__ == "__main__":
    main()

Le --dry-run indicateur affiche la requête exacte sans l’envoyer, en masquant la clé. Le voici avec une cible délicate contenant un espace, un ?, et un &:

python wsa_scrape.py 'https://example.com/a b?x=1&y=2' --render --country US --json --dry-run

https://api.webscrapingapi.com/v2?api_key=REDACTED&url=https%3A%2F%2Fexample.com%2Fa+b%3Fx%3D1%26y%3D2&render_js=1&country=us&json_response=1

Node.js (Node 18 ou version ultérieure, intégré fetch et URLSearchParams)

// Build a Scraper API request URL in Node 18+ without sending it.
// URLSearchParams handles encoding of the target URL and the extract_rules JSON.
const ENDPOINT = "https://api.webscrapingapi.com/v2";

export function buildScrapeUrl(apiKey, target, opts = {}) {
  const params = new URLSearchParams({ api_key: apiKey, url: target });
  if (opts.renderJs) params.set("render_js", "1");
  if (opts.country) params.set("country", opts.country);
  if (opts.extractRules) params.set("extract_rules", JSON.stringify(opts.extractRules));
  return `${ENDPOINT}?${params}`;
}

const target = "https://example.com/search?q=web scraping&page=2";
const url = buildScrapeUrl("REDACTED", target, {
  renderJs: true,
  country: "us",
  extractRules: { title: { selector: "h1", output: "text" } },
});
console.log(url);

// Round-trip check: the API sees exactly the original target and rules.
const parsed = new URL(url).searchParams;
console.log("url param decodes to original:", parsed.get("url") === target);
console.log("extract_rules parses:", JSON.parse(parsed.get("extract_rules")).title.selector);

// Live call (server-side only): uncomment with WSA_API_KEY set.
// const res = await fetch(buildScrapeUrl(process.env.WSA_API_KEY, "https://example.com"));
// console.log(res.status, res.headers.get("wsa-call-credit-usage"), (await res.text()).slice(0, 200));

Résultat :

https://api.webscrapingapi.com/v2?api_key=REDACTED&url=https%3A%2F%2Fexample.com%2Fsearch%3Fq%3Dweb+scraping%26page%3D2&render_js=1&country=us&extract_rules=%7B%22title%22%3A%7B%22selector%22%3A%22h1%22%2C%22output%22%3A%22text%22%7D%7D
url param decodes to original: true
extract_rules parses: h1

Pourquoi l’encodage est important. L’URL cible est intégrée dans la chaîne de requête d’une autre URL. Si vous collez https://example.com/search?q=web scraping&page=2 telle quelle, la & met fin au url paramètre prématurément, et page=2 parvient à l’API en tant que paramètre distinct. Le scraping « fonctionne » toujours, mais sur la mauvaise page. L’encodage en pourcentage, défini dans la RFC 3986, transforme ? en %3F et & en %26 , ce qui permet de conserver l’intégralité de la cible. Laissez une bibliothèque s’en charger : URLSearchParams dans Node, params= dans Requests, ou --data-urlencode dans curl. La vérification aller-retour ci-dessus prouve que l’API reçoit exactement la chaîne de caractères avec laquelle vous avez commencé.

Vous préférez une bibliothèque cliente ? WebScrapingAPI propose des SDK pour Node.js, Python, Java, PHP et Rust, ainsi qu’une intégration Scrapy. Pour l’analyse et l’exploration au-delà de l’appel d’API, consultez ces modèles de scraping en Python au-delà de l’appel d’API.

Documentation : Envoyer une requête.

Seuls api_key et url sont obligatoires. Ajoutez render_js pour les pages rendues côté client, country, city, state ou asn pour la localisation, extract_rules ou json_response pour une sortie structurée, async pour les pages lentes, et method avec un corps pour les requêtes POST, PUT ou PATCH. La valeur par défaut de `timeout` est de 120 000 millisecondes, et sa limite maximale est de 120 000 millisecondes.

Tableau 1 : Paramètres de l’API Scraper

Les paramètres booléens acceptent 1 ou true pour activer une fonctionnalité et 0 ou false pour la désactiver ; ainsi, render_js=1 et render_js=true signifient la même chose. snapshot_id remplace url plutôt que de le joindre : vous ne l’envoyez que lorsque vous récupérez le résultat d’une tâche asynchrone.

Les méthodes POST, PUT et PATCH sont dirigées vers le même /v2 point de terminaison avec une body charge utile, et la documentation les indique comme étant en version bêta. Testez-les sur une cible « echo » inoffensive telle que https://httpbin.org/post avant de les diriger vers un véritable formulaire. Si vous préférez un échec rapide plutôt que d’attendre jusqu’à deux minutes pour une cible lente, réglez timeout une valeur inférieure en millisecondes.

Commencez chaque nouvelle cible avec les deux paramètres obligatoires, examinez la réponse obtenue, puis ajoutez les options une par une. Chaque option doit justifier sa présence en corrigeant un élément que vous avez repéré dans la réponse brute.

Documentation : Paramètres de l’API.

N’activez render_js=1 que lorsque les données dont vous avez besoin sont absentes du code HTML brut, car la page les génère via JavaScript. Effectuez d’abord une requête sans rendu et vérifiez la présence de vos champs cibles. Le rendu ne coûte pas de crédits supplémentaires sur l’API Scraper, mais il est plus lent qu’une simple requête HTTP ; utilisez-le donc au cas par cas.

Le test nécessite une seule requête. Choisissez une valeur visible dans un navigateur classique, comme un prix, récupérez la page sans rendu, puis recherchez-la dans le corps de la réponse. Si elle est présente, ignorez le rendu. Si elle est manquante, cela signifie que la page la génère via JavaScript après le chargement ; réessayez donc avec render_js=1.

Prenez cette décision par cible, et non par projet, et enregistrez ce paramètre à côté de chaque cible dans votre configuration. Les pages de listes d’un site peuvent renvoyer du code HTML complet, tandis que ses pages de produits chargent les prix à partir d’un script.

Le rendu interagit également avec les erreurs. La documentation mentionne une page d’erreur renvoyée après la render_js a été désactivée comme l’une des causes d’une réponse 422. C’est pourquoi la politique de nouvelle tentative décrite dans ce guide effectue exactement une nouvelle tentative avec la page rendue après un 422 avant d’abandonner. Vous pouvez également combiner le rendu avec json_dom=1 si vous souhaitez que la page rendue soit une arborescence JSON.

Le rendu a toutefois ses limites. Si les données n’apparaissent qu’après avoir attendu un élément spécifique, cliqué sur un bouton, fait défiler la page, saisi du texte dans un champ ou pris une capture d’écran, vous dépassez le cadre d’une simple requête de l’API Scraper. C’est là qu’intervient l’API Browser.

Ajoutez un code pays à deux lettres, tel que « us », « de » ou « gb ». Affinez encore votre recherche avec le nom de la ville (en minuscules, sans espaces), l’État pour les villes américaines ou australiennes, ou « asn » pour choisir un réseau. Le géociblage n’entraîne aucun coût supplémentaire en crédits. La disponibilité des cibles par ville et par ASN peut varier selon le forfait et la zone géographique ; rabattez-vous donc sur le niveau national si nécessaire.

Les prix, les stocks, la langue et les résultats de recherche varient souvent en fonction de la localisation du visiteur. Le country paramètre achemine votre requête via un proxy situé dans ce pays, et city, state, et asn affiner encore davantage votre recherche. city nécessite toujours countryet state sert à lever les ambiguïtés entre les villes dans us ou au.

Pour confirmer l’itinéraire avant de vous y fier, interrogez un service d’écho IP. Cette requête demande une sortie à Berlin et renvoie l’adresse IP vue par la cible :

curl --get "https://api.webscrapingapi.com/v2" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "url=https://httpbin.org/ip" \
  --data-urlencode "country=de" \
  --data-urlencode "city=berlin"

Le ciblage au niveau national est proposé pour toutes les zones géographiques dans chaque forfait. Un ciblage plus précis est moins certain : la disponibilité exacte peut dépendre du forfait en cours, de la zone géographique et de l’itinéraire. Considérez donc la ville et l’ASN comme des demandes, et non comme des garanties. Si l’une n’est pas disponible, réessayez au niveau national et confirmez les emplacements dont votre charge de travail a besoin pendant la période d’essai.

Google est le seul endroit où vous ne devriez pas vous tourner country. La documentation indique de ne pas combiner le paramètre propre à Google gl avec ceux de l’API Scraper country dans une même requête. Pour les résultats de recherche, utilisez l’API SERP, qui intègre la localisation et la langue directement dans la recherche elle-même.

Transmettez les `extract_rules` sous la forme d’un objet sérialisé en JSON qui associe les noms de sortie à des sélecteurs CSS ou XPath. Chaque règle peut renvoyer du texte, du code HTML, un attribut, un tableau ou des champs imbriqués, le tout pour chaque correspondance et nettoyé pour supprimer les espaces. L’API renvoie alors un objet JSON contenant une propriété par règle au lieu de la page entière.

La forme la plus concise associe un nom à un sélecteur CSS et renvoie le texte de la première occurrence :

{"title": "h1"}

La forme « objet de règle » ajoute des options. Utilisez-la lorsque vous avez besoin d’un attribut, de code HTML, de toutes les occurrences ou d’un analyseur de tableaux :

{
  "title": {"selector": "h1", "output": "text"},
  "links": {"selector": "a", "output": "@href", "all": 1}
}

Les options sont les suivantes :

• selector: un sélecteur CSS ou une expression XPath. Les sélecteurs commençant par / sont traités comme du XPath, sauf si vous définissez selector_type à css ou xpath.
• output: text (valeur par défaut), html, @attr pour un attribut tel que @href, table_json, table_array, ou un objet de règle imbriqué.
• all: 1 renvoie toutes les correspondances, 0 uniquement la première.
• clean: 1 supprime les espaces et les sauts de ligne en début et en fin de texte.

Les règles imbriquées gèrent les cartes, les lignes ou les blocs de résultats de recherche répétés. Vous sélectionnez l’élément externe avec all: 1, puis définissez les champs à extraire de chaque correspondance. La réponse encapsule chaque valeur dans une liste ; attendez-vous donc à "title": ["..."] plutôt qu’une chaîne de caractères simple.

Prévisualisez vos sélecteurs sur une copie enregistrée de la page avant de dépenser des crédits. Enregistrez une fois le code HTML de la cible, puis itérez localement sur vos règles jusqu’à ce qu’elles renvoient le résultat escompté. Le script ci-dessous est une approximation locale permettant de vérifier les sélecteurs CSS avec Beautiful Soup, et non avec le moteur propre à l’API, mais il prend en charge les options de règles présentées ici. Installez-le avec pip install beautifulsoup4.

Le script de prévisualisation (fixture.html):

<html><body>
  <h1>  Example Store  </h1>
  <div class="result"><h2>Blue Mug</h2><a href="/p/blue-mug">view</a><span class="price">$12.00</span></div>
  <div class="result"><h2>Red Mug</h2><a href="/p/red-mug">view</a><span class="price">$14.50</span></div>
  <table id="specs"><tr><th>Size</th><th>Material</th></tr><tr><td>350 ml</td><td>Ceramic</td></tr></table>
</body></html>

Le script de prévisualisation (preview_rules.py):

"""Preview extract_rules selectors locally on saved HTML before spending credits.

This is a local approximation for checking CSS selectors, not the API's own engine.
It supports the rule options used here: selector, output (text, html, @attr, nested), all, clean.
"""
import json
import sys
from bs4 import BeautifulSoup

RULES = {
    "title": {"selector": "h1", "output": "text", "clean": 1},
    "products": {
        "selector": ".result",
        "all": 1,
        "output": {
            "name": {"selector": "h2", "output": "text"},
            "url": {"selector": "a", "output": "@href"},
            "price": {"selector": ".price", "output": "text"},
        },
    },
}


def apply_rule(node, rule):
    if isinstance(rule, str):
        rule = {"selector": rule}
    matches = node.select(rule["selector"])
    if not rule.get("all"):
        matches = matches[:1]
    out = rule.get("output", "text")
    values = []
    for m in matches:
        if isinstance(out, dict):
            values.append({k: first(apply_rule(m, r)) for k, r in out.items()})
        elif out == "html":
            values.append(str(m))
        elif out.startswith("@"):
            values.append(m.get(out[1:]))
        else:
            text = m.get_text()
            values.append(text.strip() if rule.get("clean") else text)
    return values


def first(v):
    return v[0] if v else None


html = open(sys.argv[1] if len(sys.argv) > 1 else "fixture.html").read()
soup = BeautifulSoup(html, "html.parser")
print(json.dumps({k: apply_rule(soup, r) for k, r in RULES.items()}, indent=2))
print("extract_rules param:", json.dumps(RULES, separators=(",", ":"))[:80], "...")

Résultat :

{
  "title": [
    "Example Store"
  ],
  "products": [
    {
      "name": "Blue Mug",
      "url": "/p/blue-mug",
      "price": "$12.00"
    },
    {
      "name": "Red Mug",
      "url": "/p/red-mug",
      "price": "$14.50"
    }
  ]
}
extract_rules param: {"title":{"selector":"h1","output":"text","clean":1},"products":{"selector":".re ...

Une fois que l'aperçu vous convient, transmettez le même RULES dictionnaire build_params(..., extract_rules=RULES) au client Python, qui se chargera de le sérialiser et de l’encoder pour vous. C’est en construisant la chaîne de requête à la main que la plupart des erreurs se produisent. Si la valeur n’est pas un objet converti en chaîne de caractères, l’API rejette la requête avec une erreur de validation :

{"status": "Failure", "status_code": 400, "error": "Key `extract_rules` must be a stringified object."}

Les règles, le schéma et la mise à jour des sélecteurs lorsque le site change relèvent entièrement de votre responsabilité.

Documentation : Règles d’extraction.

Ajoutez json_response=1 pour encapsuler le résultat au format JSON avec les en-têtes de la cible, le code d'état initial, le corps (de type html, json ou b64), le coût en crédits, ainsi que les microdonnées extraites et les métadonnées JSON-LD. Utilisez-la lorsque votre pipeline stocke des métadonnées ou a besoin du code d'état réel de la cible. Sinon, analysez le corps brut.

Par défaut, l’API Scraper renvoie directement le corps de la page, ce qui correspond aux attentes de la plupart des analyseurs HTML. L’enveloppe JSON est destinée aux pipelines qui ont besoin d’en savoir plus sur chaque requête : quel statut la cible a-t-elle réellement renvoyé, quel en a été le coût et quelles données structurées la page contenait-elle ?

L’enveloppe comporte six champs : headers (les en-têtes de réponse de la cible), cost (les crédits pour la requête), initial-status-code (le premier code d'état de la cible), body (le contenu de la page), type (html, json, ou b64), et metadata (les microdonnées extraites et le JSON-LD).

Cet analyseur vérifie le statut de la cible avant d’enregistrer quoi que ce soit, décode les corps binaires et lit le coût. L’entrée est un fichier d’exemple qui reflète l’ensemble de champs documenté, et non une sortie en temps réel :

"""Parse a json_response=1 envelope. sample_envelope.json mirrors the documented field set;
it is a SAMPLE, not live output."""
import base64
import json
import sys
from bs4 import BeautifulSoup

env = json.load(open(sys.argv[1] if len(sys.argv) > 1 else "sample_envelope.json"))

status = env["initial-status-code"]
if status >= 400:
    raise SystemExit(f"Target answered {status}; inspect before storing")

body = env["body"]
if env.get("type") == "b64":               # binary targets arrive base64-encoded
    body = base64.b64decode(body)

print("cost (credits):", env["cost"])
print("content-type:", env["headers"].get("content-type"))
print("json-ld blocks:", len(env["metadata"]["json-ld"]))
if env.get("type") == "html":
    print("title:", BeautifulSoup(body, "html.parser").title.get_text())

Résultat sur l’exemple :

cost (credits): 1
content-type: text/html; charset=UTF-8
json-ld blocks: 0
title: Example Domain

Il existe également json_dom=1, qui renvoie la page sous la forme d’une arborescence JSON de type DOM. Si vous souhaitez obtenir des champs spécifiques, les règles d’extraction sont généralement plus simples que de parcourir l’arborescence dans son intégralité.

Vous n’avez pas besoin de l’enveloppe pour suivre le coût. Chaque réponse comporte des en-têtes personnalisés avec un WSA- préfixe :

• WSA-Scraped-Resolved-Url: l’URL finale après les redirections
• WSA-Scraped-Headers: les en-têtes de réponse de la cible
• WSA-Client-Cookies: les cookies définis par JavaScript après le chargement de la page
• WSA-Call-Credit-Usage: les crédits utilisés par cette requête
• WSA-Current-Credit-Usage: nombre total de crédits utilisés après cette requête

Enregistrez les deux en-têtes de crédits à chaque appel. Le client Python ci-dessus collecte déjà tous les WSA- en-têtes dans son usage dictionnaire. Après une semaine d’exécution, ces journaux vous indiquent quelles cibles coûtent le plus cher et quel forfait vous convient. Pour ce qui est du stockage et de la validation dans le cadre de ce même travail, consultez l’article « Créer votre premier pipeline de données fiable ».

Envoyez la requête avec async=true. L’API met le scraping en file d’attente et renvoie immédiatement un response_id. Par la suite, appelez le même point de terminaison /v2 en définissant api_key et snapshot_id sur cet identifiant pour récupérer la page terminée. Effectuez des interrogations avec des délais croissants plutôt que de maintenir les connexions ouvertes, et stockez l’identifiant avec la tâche.

Une requête synchrone maintient la connexion ouverte jusqu’à ce que la page soit renvoyée, pendant un maximum de 120 secondes. Cela convient pour quelques URL, mais s’avère peu pratique pour les cibles lentes, les lots volumineux ou les travailleurs qui ne peuvent pas attendre deux minutes par requête. Le mode asynchrone divise l’appel en deux étapes : l’envoi et la collecte :

"""Queue a long scrape with async=true, then poll by snapshot_id.

Needs WSA_API_KEY. Without it, prints the two request shapes (key redacted)."""
import os
import time
import requests

ENDPOINT = "https://api.webscrapingapi.com/v2"
key = os.environ.get("WSA_API_KEY")
target = "https://example.com/"

if not key:
    for p in ({"api_key": "REDACTED", "url": target, "async": "true"},
              {"api_key": "REDACTED", "snapshot_id": "<response_id>"}):
        print(requests.Request("GET", ENDPOINT, params=p).prepare().url)
    raise SystemExit("dry run: set WSA_API_KEY to run live")

job = requests.get(ENDPOINT, params={"api_key": key, "url": target, "async": "true"}, timeout=30).json()
snapshot_id = job["response_id"]
for delay in (2, 4, 8, 16, 30, 30):
    time.sleep(delay)
    r = requests.get(ENDPOINT, params={"api_key": key, "snapshot_id": snapshot_id}, timeout=60)
    if r.ok and r.text.lstrip().startswith("<"):
        print(r.text[:200])
        break
    print("not ready:", r.status_code, r.text[:120])

Sans clé, le script affiche les deux formats de requête qu’il enverrait :

https://api.webscrapingapi.com/v2?api_key=REDACTED&url=https%3A%2F%2Fexample.com%2F&async=true
https://api.webscrapingapi.com/v2?api_key=REDACTED&snapshot_id=%3Cresponse_id%3E
dry run: set WSA_API_KEY to run live

La boucle d’interrogation est délibérément prudente. Elle observe un délai entre chaque tentative et considère tout ce qui n’est pas une page HTML terminée comme « pas encore prêt ». En production, enregistrez le response_id avec l’enregistrement de la tâche dès que vous l’obtenez, afin qu’un redémarrage du worker ne fasse pas perdre les résultats finalisés. Récupérez les instantanés rapidement plutôt que de supposer qu’ils attendront indéfiniment.

Traitez les codes 400, 401, 403 et 406 comme des corrections à apporter à votre requête ou à votre compte, et non comme des tentatives de réessai. Attendez un peu puis réessayez en cas de codes 429, 500 et 503. Un code 422 signifie que l’API a accepté la requête mais n’a pas pu mener à bien le scraping ; par exemple, une page de vérification renvoyant un statut HTTP 200. Réessayez donc une fois en effectuant le rendu avant d’abandonner.

Tableau 2 : Codes d’état et actions à effectuer dans votre code

La scrape() fonction du client Python implémente ce tableau. Les erreurs définitives (400, 401, 403, 406) entraînent un arrêt immédiat avec le texte de la réponse, car renvoyer la même requête échouerait de la même manière. Les erreurs pouvant faire l’objet d’une nouvelle tentative (429, 500, 503) sont gérées avec un délai d’attente exponentiel, plafonné à 30 secondes, pour un maximum de quatre tentatives. Un code 422 sur une requête non traitée déclenche une nouvelle tentative avec traitement. Un code 422 persistant est alors traité comme n’importe quelle autre erreur pouvant faire l’objet d’une nouvelle tentative, jusqu’à épuisement du nombre de tentatives.

Un code 401 mérite qu’on s’y attarde, car il recouvre deux problèmes différents. Une clé manquante renvoie ceci :

{"error":"Access denied. No key `api_key` provided."}

Ce même code indique également que votre compte a épuisé son quota de crédit ; vérifiez donc l’utilisation de votre forfait avant de faire tourner vos clés.

Pour le code 429, la solution réside généralement dans la gestion de la concurrence, et non dans la vitesse. Les forfaits autorisent entre 5 et 500 requêtes simultanées ; adaptez donc la taille de votre pool de travailleurs à votre forfait plutôt que de le laisser croître jusqu’à ce que l’API renvoie une erreur. La référence MDN sur le code 429 traite du statut lui-même. Si une cible continue d’échouer après plusieurs tentatives, appliquez ces solutions pour résoudre les blocages avant de changer d’outils.

Documentation : Réponses et erreurs.

Les forfaits sont calculés en fonction du nombre de requêtes mensuelles : Starter à 19 $ pour 7 000 requêtes, Basic à 49 $ pour 20 000, Standard à 99 $ pour 45 000, Advanced à 149 $ pour 100 000, Premium à 249 $ pour 180 000 et Pro à 599 $ pour 450 000. La version d'essai comprend 5 000 requêtes. Le rendu JavaScript et le géociblage ne coûtent aucun crédit supplémentaire, quel que soit le forfait.

Tableau 3 : Formules de l’API Scraper (prix en octobre 2026)

Le prix effectif pour 1 000 requêtes diminue de près de moitié entre la formule Starter et la formule Pro ; le volume est donc plus déterminant que les fonctionnalités lors du choix d’une formule. La concurrence est également un facteur important : si votre pipeline nécessite 100 requêtes simultanées, cela fixe un seuil minimum, quel que soit le volume mensuel.

Pour connaître vos dépenses réelles, utilisez le coût par appel indiqué par l’API : le cost champ de l’enveloppe JSON ou l’ WSA-Call-Credit-Usage en-tête. Testez votre combinaison cible réelle pendant la période d’essai, enregistrez ces valeurs et extrapolez-les sur un mois. Cela vous indiquera quelle formule vous convient le mieux, bien mieux que n’importe quelle estimation.

Utilisez l’API Scraper lorsque vous disposez d’URL et que vous avez besoin de récupérer la page. Utilisez l’API Browser lorsque la page nécessite des temps d’attente, des clics, de la saisie ou des captures d’écran. Utilisez l’API SERP pour les résultats de recherche, l’API Crawl pour un ensemble délimité de pages associées, et l’API Data pour les enregistrements structurés provenant de sources prises en charge.

WebScrapingAPI commercialise cinq API d’accès au Web. Leurs domaines d’application se recoupent moins que ne le laissent supposer leurs noms, car chacune part d’une entrée différente.

Tableau 4 : Quelle API d’accès Web convient à votre tâche ?

Parcourez ces questions dans l'ordre et arrêtez-vous dès la première réponse positive :

1. Partez-vous d’une requête de recherche ? Utilisez l’API SERP. Elle renvoie des résultats structurés par moteur, emplacement et langue, ce qui vous évite d’analyser vous-même les pages de résultats.
2. Votre source fait-elle partie des sources prises en charge par l’API Data, et souhaitez-vous obtenir des enregistrements plutôt que des pages ? Utilisez l’API Data. Elle couvre 116 sources publiques prises en charge, et WebScrapingAPI gère les analyseurs.
3. Avez-vous besoin d’un ensemble défini de pages associées plutôt que d’une seule URL à la fois ? Utilisez l’API Crawl pour une collecte multipages délimitée.
4. La page nécessite-t-elle des temps d’attente, des clics, de la saisie, des étapes de navigation ou une capture d’écran ? Utilisez l’API Browser, qui exécute un navigateur hébergé à la suite d’une requête REST.
5. Sinon, utilisez l’API Scraper, render_js=1 uniquement si le code HTML brut ne contient pas vos données.

Ces API se combinent également très bien. Un workflow courant consiste à utiliser l’API SERP pour découvrir les URL des résultats, à laisser votre application sélectionner celles qui sont pertinentes, puis à récupérer ces pages à l’aide de l’API Scraper ou de l’API Browser. Les tarifs de l’API Browser et de l’API Crawl sont établis sur devis. L’API Scraper, l’API SERP et la source Amazon de l’API Data proposent des forfaits mensuels, à compter d’octobre 2026.

Pour un comparatif complet, incluant le fonctionnement de chaque API et ce qui reste dans votre application, comparez les cinq API Web Access.

Web MCP est un serveur hébergé utilisant le protocole MCP (Model Context Protocol) accessible à l’adresse https://mcp.webscrapingapi.com/mcp. Votre agent se connecte à l’aide d’un jeton MCP dédié et récupère les données web_read et web_read_more via l’API Scraper ou l’API Browser, ainsi que web_search via l’API SERP. Il utilise vos forfaits et quotas existants, et l’ajout d’un jeton n’entraîne aucune augmentation de quota.

Web MCP n’est pas un produit distinct à acheter. Il s’agit d’une couche de connexion s’ajoutant à l’accès aux API dont dispose déjà votre compte, sans aucun logiciel à installer ni serveur à faire tourner.

Ce dont vous avez besoin. Vous devez disposer d’un compte WebScrapingAPI avec accès à l’API SERP, à l’API Web Scraping ou à l’API Browser. Vous avez également besoin d’un client MCP prenant en charge le transport HTTP Streamable avec un en-tête Authorization: Bearer , selon le schéma de jeton défini dans la RFC 6750. Les clients ne prenant en charge que la connexion OAuth ne peuvent pas se connecter.

Configuration. En tant que titulaire du compte, ouvrez MCP dans le tableau de bord, copiez l’URL du serveur, puis sélectionnez « Créer un jeton ». Le jeton n’apparaît qu’une seule fois ; enregistrez-le donc immédiatement dans le magasin de secrets de votre client ou dans un gestionnaire de mots de passe. Chaque compte peut disposer de dix jetons actifs au maximum ; en cas de perte d’un jeton, celui-ci doit être révoqué et remplacé. Votre clé API produit n’est pas un jeton MCP et n’a pas sa place dans les paramètres de connexion. Les clients qui acceptent un mcpServers objet utilisent une configuration comme celle-ci :

{
  "mcpServers": {
    "webscrapingapi": {
      "url": "https://mcp.webscrapingapi.com/mcp",
      "headers": { "Authorization": "Bearer ${WSA_MCP_TOKEN}" }
    }
  }
}

Remplacez le paramètre fictif par votre jeton MCP accessible depuis Tableau de bord → MCP. Certains clients le lisent à partir d’une variable d’environnement, tandis que d’autres disposent d’un champ dédié au jeton ; la syntaxe d’interpolation varie selon le client. Définissez le délai d’expiration de l’outil client sur une valeur supérieure à 60 secondes.

Tableau 5 : Outils Web MCP

Votre client ne détecte que les outils pris en charge par votre compte. Sans accès à l’API SERP, l’agent peut toujours lire les URL que vous lui fournissez, mais il ne peut pas effectuer de recherche.

Routage et facturation. Les lectures utilisent l’API Scraper lorsque votre compte en dispose, sinon l’API Browser, et un utilisateur avancé peut choisir l’une ou l’autre à l’aide de l’ backend argument. Les lectures via l’API Scraper utilisent des crédits et sont statiques par défaut. Lorsque l’agent définit render_js: true, cela correspond à une nouvelle requête facturée à l’utilisation. Les lectures via l’API Browser s’affichent toujours et utilisent de la bande passante. Une requête échouée ou un quota épuisé ne bascule jamais vers un autre produit.

Limites. Chaque résultat d’outil est plafonné à 16 KiB ; les pages longues sont donc transmises par morceaux que vous récupérez avec web_read_more. Les pages dont le code HTML dépasse 10 Mio renvoient une erreur, et les captures sont conservées jusqu’à une heure. Le délai d’expiration en amont est de 55 secondes. Chaque jeton autorise quatre appels d’outils simultanés et quatre sessions actives ; une session prend fin après 15 minutes d’inactivité, une heure ou 1 000 requêtes.

Pour une vue d’ensemble de la manière dont les agents utilisent les données Web en temps réel, consultez ces modèles d’accès Web par agent.

Documentation : Prise en main de Web MCP et Utilisation et erreurs.

L’API Scraper récupère une page par requête ; elle ne peut donc pas cliquer, saisir du texte, faire défiler la page ou se connecter à votre place. Les requêtes expirent au bout de 120 secondes, le nombre de requêtes simultanées est plafonné selon le forfait, et la couverture par ville ou par ASN varie. Elle ne peut pas rendre une page légalement accessible à la collecte. Choisissez une autre API ou un autre outil lorsque ces limites deviennent gênantes.

• Aucune interaction. Une requête renvoie une seule page. L’attente d’un sélecteur, les clics, la saisie de texte, le défilement et les captures d’écran relèvent de l’API Browser.
• Pas de recherche. Pour les résultats des moteurs de recherche, utilisez l’API SERP plutôt que de scraper les pages de résultats.
• Une URL à la fois. Si la tâche porte sur un ensemble défini de pages liées, l’API Crawl gère cette portée pour vous.
• Délai d’expiration de 120 secondes. Les cibles lentes et les lots volumineux doivent passer par des requêtes asynchrones.
• Concurrence en fonction du forfait. De 5 requêtes parallèles en version d’essai à 500 en version Pro. Adaptez le nombre de vos workers en conséquence.
• La couverture géographique varie. Le ciblage au niveau national est large, mais la disponibilité au niveau des villes et des ASN dépend du forfait, de la zone géographique et de l’itinéraire.
• Les pages complexes peuvent tout de même échouer. L’API gère l’accès pour vous, mais certaines cibles renvoient un code d’erreur 422. Elle ne garantit pas la résolution des CAPTCHA ; prévoyez donc des échecs occasionnels sur les cibles les plus difficiles.

Il existe également une responsabilité que n’aucune API ne peut supprimer. C’est à vous de définir quelles sources sont éligibles et à quoi servent les données. Utilisez le service uniquement pour les pages publiques que vous êtes autorisé à collecter, consultez les conditions d’utilisation de chaque site, respectez les règles relatives aux données personnelles et les politiques concernant les robots.

Pour connaître les bonnes pratiques permettant de maintenir un scraper en bon état de fonctionnement pendant des mois, consultez ces recommandations sur le cycle de vie, accompagnées de code fonctionnel. Vous envisagez d’autres options que WebScrapingAPI ? Notre guide comparatif des API de scraping proposées par d’autres fournisseurs couvre l’ensemble du secteur.

Envoyez une requête HTTP au point de terminaison de l’API avec votre clé API et l’URL souhaitée, puis lisez la page à partir de la réponse. Avec WebScrapingAPI, il s’agit d’une requête GET vers https://api.webscrapingapi.com/v2 avec une clé API et une URL encodée. N’ajoutez des paramètres de rendu, de localisation ou d’extraction que lorsque la cible en a besoin.

Installez Requests, placez votre clé dans une variable d’environnement, puis transmettez « api_key » et l’URL dans l’argument « params » afin que Requests les encode. Vérifiez le code d’état, réessayez en cas de réponses 429 et 5xx avec un délai de réessai, puis analysez le corps de la réponse à l’aide de votre analyseur HTML ou demandez à l’API de renvoyer des données au format JSON à l’aide de « extract_rules ».

Oui. L’essai de l’API Scraper comprend 5 000 requêtes et est entièrement gratuit au départ, avec cinq requêtes simultanées. Le rendu JavaScript et le ciblage par pays sont inclus, ce qui vous permet de tester les cibles qui vous intéressent avant de choisir une formule payante. Les formules payantes commencent à 19 $ par mois pour 7 000 requêtes.

Non. Sur l’API Scraper, les paramètres `render_js=1` et le ciblage géographique n’utilisent pas de crédits supplémentaires, quel que soit le forfait. Le rendu est toutefois plus lent qu’une simple requête `fetch` ; n’activez-le donc que pour les pages dont les données sont absentes du code HTML initial. Vérifiez l’en-tête « WSA-Call-Credit-Usage » pour connaître la consommation de crédits de chaque appel.

Il s’agit d’un service qui récupère des pages Web pour vous et renvoie leur contenu ou des champs sélectionnés dans un format exploitable. Le fournisseur gère les proxys, les tentatives de connexion et les navigateurs ; vous lui envoyez une URL et des options. L’API Scraper de WebScrapingAPI renvoie du code HTML, une enveloppe JSON ou des champs sélectionnés à l’aide de règles d’extraction CSS ou XPath.

Techniquement, de nombreuses pages publiques peuvent être récupérées, mais toutes ne le devraient pas. Certains contenus sont protégés par une connexion, certaines pages nécessitent une interaction avec le navigateur, et les conditions d’utilisation du site ou les lois sur les données personnelles peuvent restreindre la collecte. Utilisez l’API Scraper pour les pages publiques que vous êtes autorisé à collecter, et l’API Browser lorsque les pages nécessitent une interaction.

Récupérez ses pages et extrayez les champs vous-même, ou confiez cette tâche à une API de scraping. Avec l’API Scraper, envoyez l’URL de la page avec des `extract_rules` qui associent les noms de champs à des sélecteurs CSS, et vous obtiendrez une réponse au format JSON. Prévisualisez d’abord les sélecteurs sur une copie enregistrée de la page pour éviter les requêtes inutiles.

L’API Scraper gère le routage par proxy, la rotation et les stratégies d’accès, mais elle ne garantit pas la résolution des CAPTCHA. Si une cible renvoie une page de vérification avec un code HTTP 200, l’API peut classer le scraping comme un échec 422 au lieu de vous transmettre un contenu erroné. Réessayez une fois avec le rendu, puis vérifiez la cible.

Vous avez besoin d’un compte WebScrapingAPI avec accès à l’API Scraper, à l’API Browser ou à l’API SERP, d’un jeton MCP dédié disponible depuis le tableau de bord, et d’un client MCP prenant en charge le protocole Streamable HTTP avec un en-tête « bearer ». Configurez le client pour qu’il pointe vers https://mcp.webscrapingapi.com/mcp. Les clients qui ne prennent en charge que la connexion OAuth ne peuvent pas se connecter.

Oui, lorsqu’il lit des pages via l’API Scraper. Chaque `web_read` est une requête normale facturée à l’utilisation, et une nouvelle tentative avec rendu constitue une requête supplémentaire. La commande `web_read_more` poursuit la même capture sans facturation supplémentaire. Les recherches utilisent votre quota d’API SERP, et la création d’un jeton MCP n’ajoute pas de quota.

L’API Scraper gère les proxys, la rotation, les nouvelles tentatives et le rendu JavaScript en une seule requête. Le rendu et le ciblage géographique ne coûtent pas de crédits supplémentaires, et les requêtes ayant échoué ne sont pas facturées. Choisissez une formule lorsque votre période d’essai vous aura permis de déterminer vos besoins.

Vous développez un agent IA ? Ajoutez l’API SERP pour que Web MCP puisse non seulement lire, mais aussi effectuer des recherches. Sa période d’essai comprend 100 recherches Google.