The official Python SDK for the Decodo Web Scraping API.

Build scraping workflows for search engines, eCommerce platforms, social media, AI tools, and more using the Decodo Web Scraping API.

• Fully typed targets and parameters with IDE autocomplete
• Sync, async, and batch scraping methods
• Built on httpx, Python 3.12+
• Typed error hierarchy for safer integrations
• Built for Python and modern tooling

Decodo Python SDK is the official Python SDK for the Decodo Web Scraping API. It provides a typed interface for interacting with Decodo targets like Google, Amazon, TikTok, Reddit, YouTube, ChatGPT, Perplexity, and more.

Instead of manually constructing HTTP requests and validating payloads, you can work with fully typed methods and target-specific parameters directly in your editor.

• Typing and autocomplete. Target parameters are fully typed for better DX and fewer mistakes.
• Unified scraping interface. Work with search engines, eCommerce platforms, social media, and AI tools through one SDK.
• Async and batch workflows. Create scraping tasks, poll statuses, and process batches at scale.
• Typed errors. Handle authentication, validation, timeout, and rate-limit failures safely.
• Minimal setup. Single dependency on httpx, no additional HTTP client required.

• Python 3.12+

pip install decodo

Create a new project:

mkdir scrape-with-decodo
cd scrape-with-decodo

pip install decodo

touch main.py

Get a Web Scraping API basic authentication token from the Decodo dashboard and use it in the following example:

# main.py
from decodo import DecodoClient, Target

client = DecodoClient(
    web_scraping_api={"token": "<basic_auth_token>"}
)

result = client.web_scraping_api.scrape({
    "target": Target.GoogleSearch,
    "query": "coffee shops",
    "geo": "United States",
    "parse": True,
})
print(result)

Run the script:

python main.py

{
  "results": [
    {
      "content": {
        "results": {
          "last_visible_page": 10,
          "page": 1,
          "parse_status_code": 12000,
          "results": {
            "local_pack": [
              {
                "items": [
                  {
                    "address": "Rochester, NY",
                    "paid": false,
                    "pos": 1,
                    "rating": 4.9,
                    "rating_count": 1700,
                    "subtitle": "Coffee shop",
                    "title": "Albunn Coffee House"
                  },
                  {
                    "address": "Rochester, NY",
                    "paid": false,
                    "pos": 2,
                    "rating": 4.8,
                    "rating_count": 937,
                    "subtitle": "Coffee shop",
                    "title": "Layali Coffee House"
                  },
                  {
                    "address": "Ocean Township, NJ",
                    "paid": false,
                    "pos": 3,
                    "rating": 4.9,
                    "rating_count": 124,
                    "subtitle": "Coffee shop",
                    "title": "Ocean Brew Co."
                  }
                ],
                "pos_overall": 1
              }
            ],
            "organic": [
              {
                "desc": "For an alternate, local view, Eater has an interesting list of what it considers Philadelphia's 21 Essential Coffee Shops.",
                "pos": 1,
                "pos_overall": 2,
                "title": "Philadelphia",
                "url": "https://www.brian-coffee-spot.com/the-coffee-spot-guide-to/usa-canada/philadelphia/"
              }
            ],
            "search_information": {
              "query": "coffee shops",
              "total_results_count": 403000000
            }
          },
          "url": "https://www.google.com/search?q=coffee+shops&hl=en&gl=us"
        },
        "errors": [],
        "status_code": 12000,
        "task_id": "7463508496927950850"
      },
      "status_code": 200,
      "url": "https://www.google.com/search?q=coffee+shops&hl=en&gl=us",
      "task_id": "7463508496927950850",
      "created_at": "2026-05-22 08:38:10",
      "updated_at": "2026-05-22 08:38:13"
    }
  ]
}

from decodo import DecodoClient

client = DecodoClient(
    web_scraping_api={"token": "<basic_auth_token>"},
    timeout_ms=120_000,  # optional, request timeout in ms (default: 180000)
)

Access the API via client.web_scraping_api.

The snippets below assume you have already imported Target (and DecodoClient where a client is constructed), for example:

from decodo import DecodoClient, Target

Waits for the scraping result before returning:

result = client.web_scraping_api.scrape({
    "target": Target.AmazonProduct,
    "query": "B09H74FXNW",
    "parse": True,
})

Creates a scraping task and returns immediately. Poll separately for task status and results:

task = client.web_scraping_api.scrape_async({
    "target": Target.GoogleSearch,
    "query": "laptop reviews",
    "parse": True,
})

meta = client.web_scraping_api.get_status(task["id"])
print(meta["status"])  # 'pending' | 'done' | 'faulted'

results = client.web_scraping_api.get_results(task["id"])

Send multiple queries or URLs in a single request:

batch = client.web_scraping_api.scrape_batch({
    "target": Target.GoogleSearch,
    "query": ["coffee", "tea", "juice"],
    "parse": True,
})

coffee_task_id = batch["queries"][0]["id"]

client.web_scraping_api.get_results(coffee_task_id)

Each target accepts one primary input parameter (url, query, product_id, or prompt) together with optional configuration. The examples below show the minimum payload to call client.web_scraping_api.scrape(...).

Target.UniversalEcommerce isn't listed above because it doesn't accept a primary input parameter like url, query, product_id, or prompt. It only accepts optional configuration fields such as callback_url.

For the full target list and parameter details, see the API documentation:

• Target list
• Parameters

The SDK raises typed errors that map to API error codes:

from decodo import (
    DecodoClient,
    DecodoError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    TimeoutError,
    Target,
)

try:
    client.web_scraping_api.scrape({
        "target": Target.GoogleSearch,
        "query": "test",
        "parse": True,
    })
except AuthenticationError:
    pass  # 401/403 — bad credentials
except RateLimitError:
    pass  # 429 — too many requests
except ValidationError as err:
    print(err.errors)  # 422 — invalid parameters
except TimeoutError:
    pass  # request timed out

• Web Scraping API
• Decodo MCP Server
• Decodo OpenClaw Skill

Build scraping workflows with the Decodo Web Scraping API:

• Start free plan
• Documentation
• Discord

Released under the MIT License.

03b68da (Initial sdk setup)