> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Brightdataserp integration

> Query search engines with geo-targeting using Bright Data's SERP API

[Bright Data](https://brightdata.com/) provides a powerful SERP API that allows you to query search engines (Google, Bing, DuckDuckGo, Yandex) with geo-targeting and advanced customization options, particularly useful for AI agents requiring real-time web information.

## Overview

### Integration details

| Class                                                              | Package                                                                  | Serializable | JS support |                                               Version                                              |
| :----------------------------------------------------------------- | :----------------------------------------------------------------------- | :----------: | :--------: | :------------------------------------------------------------------------------------------------: |
| [`BrightDataSERP`](https://pypi.org/project/langchain-brightdata/) | [`langchain-brightdata`](https://pypi.org/project/langchain-brightdata/) |       ✅      |      ❌     | ![PyPI - Version](https://img.shields.io/pypi/v/langchain-brightdata?style=flat-square\&label=%20) |

### Tool features

| Native async | Returns artifact | Return data                                                 |            Pricing           |
| :----------: | :--------------: | :---------------------------------------------------------- | :--------------------------: |
|       ❌      |         ❌        | Title, URL, snippet, position, and other search result data | Requires Bright Data account |

## Setup

The integration lives in the `langchain-brightdata` package.
pip install langchain-brightdata

### Credentials

You'll need a Bright Data API key to use this tool. You can set it as an environment variable:

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import os

os.environ["BRIGHT_DATA_API_KEY"] = "your-api-key"
```

Or pass it directly when initializing the tool:

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_brightdata import BrightDataSERP

serp_tool = BrightDataSERP(bright_data_api_key="your-api-key")
```

## Instantiation

Here we show how to instantiate an instance of the BrightDataSERP tool. This tool allows you to perform search engine queries with various customization options including geo-targeting, language preferences, device type simulation, and specific search types using Bright Data's SERP API.

The tool accepts various parameters during instantiation:

* `bright_data_api_key` (required, str): Your Bright Data API key for authentication.
* `zone` (optional, str): Bright Data zone name for the SERP API. Default is "serp". You can configure custom zones in your [Bright Data dashboard](https://brightdata.com/cp/zones).
* `search_engine` (optional, str): Search engine to use for queries. Default is "google". Other options include "bing", "yahoo", "yandex", "duckduckgo", etc.
* `country` (optional, str): Two-letter country code for localized search results (e.g., "us", "gb", "de", "jp"). Default is "us".
* `language` (optional, str): Two-letter language code for the search results (e.g., "en", "es", "fr", "de"). Default is "en".
* `results_count` (optional, int): Number of search results to return. Default is 10. Maximum value is typically 100.
* `search_type` (optional, str): Type of search to perform. Options include:
  * None (default): Regular web search
  * "isch": Images search
  * "shop": Shopping search
  * "nws": News search
  * "jobs": Jobs search
* `device_type` (optional, str): Device type to simulate for the search. Options include:
  * None (default): Desktop device
  * "mobile": Generic mobile device
  * "ios": iOS device (iPhone)
  * "android": Android device
* `parse_results` (optional, bool): Whether to return parsed JSON results. Default is False, which returns raw HTML response.

## Invocation

### Basic usage

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_brightdata import BrightDataSERP

# Initialize the tool
serp_tool = BrightDataSERP(
    bright_data_api_key="your-api-key"  # Optional if set in environment variables
)

# Run a basic search
results = serp_tool.invoke("latest AI research papers")

print(results)
```

### Advanced usage with parameters

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_brightdata import BrightDataSERP

# Initialize with default parameters
serp_tool = BrightDataSERP(
    bright_data_api_key="your-api-key",
    search_engine="google",  # Default
    country="us",  # Default
    language="en",  # Default
    results_count=10,  # Default
    parse_results=True,  # Get structured JSON results
)

# Use with specific parameters for this search
results = serp_tool.invoke(
    {
        "query": "best electric vehicles",
        "country": "de",  # Get results as if searching from Germany
        "language": "de",  # Get results in German
        "search_type": "shop",  # Get shopping results
        "device_type": "mobile",  # Simulate a mobile device
        "results_count": 15,
    }
)

print(results)
```

## Customization options

The BrightDataSERP tool accepts several parameters for customization:

| Parameter       | Type | Description                                                               |
| :-------------- | :--- | :------------------------------------------------------------------------ |
| `query`         | str  | The search query to perform                                               |
| `zone`          | str  | Bright Data zone name (default: "serp")                                   |
| `search_engine` | str  | Search engine to use (default: "google")                                  |
| `country`       | str  | Two-letter country code for localized results (default: "us")             |
| `language`      | str  | Two-letter language code (default: "en")                                  |
| `results_count` | int  | Number of results to return (default: 10)                                 |
| `search_type`   | str  | Type of search: None (web), "isch" (images), "shop", "nws" (news), "jobs" |
| `device_type`   | str  | Device type: None (desktop), "mobile", "ios", "android"                   |
| `parse_results` | bool | Whether to return structured JSON (default: False)                        |

## Zone configuration

Bright Data uses "zones" to manage different API configurations. You can set the zone at initialization or override it per-request.

### Setting zone at initialization

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_brightdata import BrightDataSERP

# Initialize with a custom zone
serp_tool = BrightDataSERP(
    bright_data_api_key="your-api-key",
    zone="my_custom_serp_zone"
)
```

### Overriding zone per-request

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Override zone for a specific request
results = serp_tool.invoke({
    "query": "AI news",
    "zone": "different_zone"
})
```

Zone names must match the zones configured in your [Bright Data dashboard](https://brightdata.com/cp/zones).

## Use within an agent

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_brightdata import BrightDataSERP
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain.agents import create_agent


# Initialize the LLM
llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash", google_api_key="your-api-key")

# Initialize the Bright Data SERP tool
serp_tool = BrightDataSERP(
    bright_data_api_key="your-api-key",
    search_engine="google",
    country="us",
    language="en",
    results_count=10,
    parse_results=True,
)

# Create the agent
agent = create_agent(llm, [serp_tool])

# Provide a user query
user_input = "Search for 'best electric vehicles' shopping results in Germany in German using mobile."

# Stream the agent's output step-by-step
stream = agent.stream_events({"messages": user_input}, version="v3")
for snapshot in stream.values:
    snapshot["messages"][-1].pretty_print()
```

***

## API reference

* [Bright Data API Documentation](https://docs.brightdata.com/scraping-automation/serp-api/introduction)

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/tools/brightdata_serp.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>