SerpApi Search Tools

Give Python AI agents live web, news, maps, image, shopping, video, hotel, and flight search with easy-to-use, customizable tools.

Read the full documentation for guides, SDK examples, recipes, and the API reference.

serpapi-search-tools connects SerpApi to popular Python agent SDKs. Enhance your AI agent with real-time search data across the capabilities it needs:

from serpapi_search_tools import maps_search, news_search, web_search

tools = [
    web_search(),
    news_search(),
    maps_search(),
]

When one supported agent SDK is installed, the package detects it and creates tools ready for that SDK.

Supported agent SDKs

Install

If your agent SDK is already installed, add only the base package:

pip install serpapi-search-tools

If you want this package to install a compatible agent SDK too, choose its extra. For example:

pip install "serpapi-search-tools[openai-agents]"

Extras are available for all supported SDKs listed above.

Set a SerpApi key:

export SERPAPI_API_KEY="your-key"

SERPAPI_KEY is also supported. A directly supplied api_key= takes precedence over environment variables.

Quickstart: automatic SDK detection

This quickstart uses OpenAI Agents SDK to demonstrate automatic detection. It assumes the SDK is already installed in your environment (install it with pip install openai-agents if needed). Then add the base package:

pip install serpapi-search-tools

With one supported SDK installed, create the tool without any configuration. The package detects OpenAI Agents SDK and returns its native FunctionTool. This example also expects the OPENAI_API_KEY used by your agent.

from agents import Agent, Runner

from serpapi_search_tools import web_search

agent = Agent(
    name="research-agent",
    instructions="Use web search when the answer needs current information.",
    tools=[web_search()],
)

result = Runner.run_sync(
    agent,
    "Find three recent Python packaging changes and explain why they matter.",
)
print(result.final_output)

Quickstart: LangChain

Install the LangChain extra and the model backend used by this example:

pip install "serpapi-search-tools[langchain]" langchain-openai

The langchain extra installs a compatible LangChain version. langchain-openai provides this example's model integration; replace it with the backend your LangChain application uses. With langchain-openai, set OPENAI_API_KEY before running the agent.

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

from serpapi_search_tools import maps_search, news_search, web_search

agent = create_agent(
    model=ChatOpenAI(model="gpt-5.4-mini", temperature=0),
    tools=[
        web_search(),
        news_search(),
        maps_search(),
    ],
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "Research coffee culture in Austin using current reporting, "
                    "local places, and general web sources."
                ),
            }
        ]
    }
)
print(result["messages"][-1].content)

The constructors use automatic SDK detection, just as in the first quickstart. For multi-SDK environments and explicit selection, see Agent SDKs.

For a step-by-step explanation, keys, customization, and troubleshooting, read the detailed quickstart.

Browse the runnable examples for focused integrations or the agent cookbook for complete, task-oriented agents built with every supported SDK.

Choose the right tool

General web

from serpapi_search_tools import WebSearchEngine, web_search

tool = web_search(
    allowed_engines=[WebSearchEngine.GOOGLE_LIGHT, WebSearchEngine.BING],
    default_engine=WebSearchEngine.GOOGLE_LIGHT,
)

SerpApi supports multiple general web search engines, including Google Light, Google, Bing, Yahoo, and DuckDuckGo. Google Light is the default because it provides fast, general-purpose web results. Use allowed_engines to choose which engines are available and default_engine to select the initial one.

News, maps, images, and videos

from serpapi_search_tools import images_search, maps_search, news_search, videos_search

tools = [
    news_search(),
    maps_search(),
    images_search(),
    videos_search(),
]

news_search supports keyword searches in Google News. maps_search searches Google Maps and accepts optional location, zoom (3 through 30), and nearby fields. Use nearby=True for “near me” intent with a separate location; leave it false when the query already names a city or area. Place details, reviews, and directions use different SerpApi APIs and are not part of this search tool.

Shopping

from serpapi_search_tools import ShoppingSearchEngine, shopping_search

tool = shopping_search(
    allowed_engines=[
        ShoppingSearchEngine.GOOGLE_SHOPPING,
        ShoppingSearchEngine.AMAZON,
        ShoppingSearchEngine.WALMART,
        ShoppingSearchEngine.EBAY,
    ],
)

The package routes one human query to each marketplace's native field: Google Shopping uses q, Amazon uses k, Walmart uses query, and eBay uses _nkw.

Travel

from serpapi_search_tools import flights_search, hotels_search, travel_explore_search

travel_tools = [
    hotels_search(),
    flights_search(),
    travel_explore_search(),
]

These constructors create hotel, flight, and destination-discovery tools for the detected agent SDK.

Hotels

hotels_search lets the agent provide a destination, dates, and guest details. Hotel dates use YYYY-MM-DD. Checkout must be after check-in. When children is nonzero, provide exactly one age from 1 through 17 per child; use 1 for a child under one year old.

Flights

flights_search lets the agent provide route, date, cabin, and passenger details. It requires an origin, destination, and outbound date. Omitting return_date creates a one-way request; including it creates a round trip. Use specific airport IATA codes such as LHR and CDG, not metropolitan codes such as LON and PAR. For a city-wide search, use a Google Knowledge Graph location ID (KGMID) beginning with /m/ or /g/, such as /m/04jpl for London or /m/05qtj for Paris. Multi-city searches are not currently supported.

Explore destinations

travel_explore_search lets the agent discover destinations and requires only a departure airport IATA code or city KGMID. It can also accept a specific arrival airport or city through arrival_id, or a region or country KGMID through arrival_area_id. Fixed outbound/return dates, cabin class, and passenger counts are optional. These travel tools send their route and date fields directly to the matching SerpApi endpoint.

Set advanced parameters in application code

Use default_params for documented SerpApi settings that should stay under your application's control, such as locale, currency, safe search, or result count. The agent continues to supply only the inputs described by its search tool.

Applications can supply documented advanced options at construction time:

tool = news_search(
    default_params={"hl": "en", "gl": "us"},
)

Typed fields and the constructor-controlled engine override colliding entries in default_params. Known incompatible combinations are rejected locally, such as Google News query plus topic tokens, Amazon keyword search plus node, or flight airline include plus exclude filters. For a multi-engine tool, the same defaults are sent to every allowed engine. Use only parameters shared by those engines, or create separate tool instances when each engine needs different defaults. Reserved keys (api_key, async, engine, and output) are rejected in default_params; use the constructor options documented below instead.

Handle search failures

The search runtime raises SerpApiSearchError for SerpApi and transport failures. Invalid tool inputs raise ValueError. Agent SDKs surface or handle tool errors differently, so use your SDK's normal tool-error mechanism. See Debugging for detailed examples.

Common factory options

Every constructor accepts:

web_search and shopping_search additionally accept allowed_engines and default_engine. The tool offers only the engine values you configured.

Supported engine documentation

• Google Search
• Google Light
• Bing
• Yahoo
• DuckDuckGo
• Google News
• Google Maps
• Google Images
• Google Shopping
• Amazon
• Walmart
• eBay
• YouTube
• Google Hotels
• Google Flights
• Google Travel Explore

For AI coding agents that need broader SerpApi API context, use SerpApi's agent-friendly documentation index (llms.txt). It links directly to Markdown API references, including APIs beyond those wrapped by this package.

More guides

• Introduction
• Quickstart
• Choose a search tool
• Usage and composition
• Configuration
• Recipes
• Agent SDKs
• Agent cookbook
• Runnable examples