Maps search with maps_search

maps_search finds places, businesses, and local services through Google Maps. The agent can provide a search query and, when useful, a separate location, zoom level, and nearby preference.

When to use it

Use it for nearby recommendations, stores, restaurants, repair services, venues, and local discovery. Choose web_search when the answer is about webpages rather than physical places.

This tool searches for places. It is not a place-details, reviews, directions, or photos tool; those SerpApi APIs require different identifiers and schemas.

Quick example

from serpapi_search_tools import maps_search

local_places = maps_search()
agent_tools = [local_places]

An agent can then call the tool with values such as:

{"query": "coffee roasters", "location": "Portland, Oregon", "zoom": 12}

Inputs the agent can provide

Field Type Required Default and constraints
query string yes Place, business name, or category; use location for a separate geographic search origin
location string no Search origin such as Austin, Texas; usually omit when query already names the city or area
zoom integer no 14; 3 covers a wide area and larger values narrow it; allowed range is 3 through 30; used with location
nearby boolean no False; set True for “near me” intent, leave false when query names a city or area, and always provide location when true

The package sends Google Maps type="search" and maps zoom to SerpApi’s z field.

Configure the tool

Constructor option Default Use it for
provider "auto" Detect one installed SDK or choose an SDK explicitly
default_params None Fix Google Maps locale or supported search filters
mode compact Return the main local result section; use SearchResultMode.FULL to keep supporting sections and all fields on retained results
response_format markdown Return Markdown by default, or use SearchResultFormat.JSON for structured fields
result_limit 10 Maximum local_results retained in either mode; an exact place_results object is retained whole
api_key None Override environment key lookup
timeout None Set the built-in client timeout
client None Add deterministic tests, caching, or request logging
include_examples True Add a local-search example to the description
name "maps_search" Distinguish multiple configured maps tools

Useful SerpApi parameters

The model already controls location, zoom, and nearby through typed fields. Use default_params for application policy such as locale:

from serpapi_search_tools import maps_search

us_places = maps_search(
    default_params={"hl": "en", "gl": "us"},
    name="us_places",
)

Google Maps also supports more search filters and pagination. Check the official reference before adding them; do not put place-detail identifiers in this search-mode tool.

What comes back

Both modes return up to result_limit local_results (10 by default). An exact-place response uses a single place_results object, which compact mode retains whole rather than treating it as a list. Place entries may include a title, address, rating, review count, category, phone, website, hours, coordinates, thumbnail, and identifiers. Compact mode omits supporting sections. Use result_limit=None to keep every returned place. Availability varies by place and query.

Common mistakes

  • Setting nearby=True without location.
  • Setting nearby=True when the query already names a city or area.
  • Repeating the same city in both query and location without a reason.
  • Passing a zoom outside 3 through 30.
  • Combining the typed location with ll, lat, or lon defaults.
  • Passing place_id or data_cid; this tool supports place search rather than the separate place-details API.
  • Expecting directions or reviews from a search-only contract.

Official SerpApi documentation

See the local discovery recipe and direct_multi_search.py for working usage.