Google Maps Search — API reference

POST

Available

/google/maps/search

Google Maps Search

Find Google Maps places using a query and location, such as coffee in Seattle. Use the separate place-detail endpoint for an identified place.

type

maps_search

result

places

Billing

2 credits

Find Google Maps places using a query and location, such as coffee in Seattle. Use the separate place-detail endpoint for an identified place.

Parameters

FieldTypeAvailabilityDescription

q

required

string

required

Search query string.

hl

optional

string

optional

Language code. Defaults to en.

gl

optional

string

optional

Country code. Defaults to us.

page

optional

number

optional

1-based page number. Defaults to 1.

lat

optional

number

optional

Map center latitude. Must be sent together with lng.

lng

optional

number

optional

Map center longitude. Must be sent together with lat.

zoom

optional

number

optional

Map zoom from 1 to 21. Defaults to 14 when coordinates are sent.

location

sample

object

Catalog sample; the API validates required fields.

sample: {"location_query":"Seattle, WA"}

query

sample

string

Catalog sample; the API validates required fields.

sample: "coffee"

json

{
  "location": {
    "location_query": "Seattle, WA"
  },
  "query": "coffee"
}

Open in Playground

Response fields

FieldTypeAvailabilityDescription

query

required

string

required

Normalized query from the request.

page

required

number

required

Current 1-based page number.

places

optional

MapsPlace[]

When local places are parsed.

Local place results.

MapsPlace Result item schema

FieldTypeAvailabilityDescription

position

optional

number

Maps Search only.

Place rank in the local result list.

name

required

string

required

Place name.

title

required

string

required

Alias for name.

feature_id

required

string

required

Google Maps feature id.

place_id

optional

string

When Google exposes it.

Google place id.

data_id

optional

string

Alias for feature_id.

Maps data id.

cid

optional

string

Derived from feature_id when possible.

Google CID.

kgmid

optional

string

When present in Maps payload.

Knowledge graph machine id.

google_maps_url

optional

string

When Google exposes a Maps URL.

Google Maps URL.

url

optional

string

google_maps_url or website fallback.

Primary place URL.

rating

optional

number

When rating is present.

Google rating.

types

optional

string[]

When categories are present.

Place type labels.

category

optional

object

When category block is parsed.

Structured category data.

address

optional

string

When address is present.

Formatted address.

address_components

optional

object

When components are present.

Street, city, postal code, country code.

plus_code

optional

object

When plus code is present.

Global and compound plus codes.

phone

optional

string

When phone is present.

Local phone number.

phone_international

optional

string

When present.

International phone number.

phone_uri

optional

string

When present.

Telephone URI.

website

optional

string

When website is present.

Business website.

website_domain

optional

string

When website domain is present.

Business website domain.

latitude

optional

number

When coordinates are present.

Latitude.

longitude

optional

number

When coordinates are present.

Longitude.

image

optional

string

When image is present.

Primary place image.

thumbnail

optional

string

Alias for image when available.

Primary image alias.

photos

optional

MapsPhoto[]

When photos are parsed.

Photo id, URL, size, and optional coordinates.

hours

optional

Record<string,string>

When hours are parsed.

Opening hours by day.

open_status

optional

object

When status is present.

Open status text and current hours.

attributes

optional

object[]

When attributes are parsed.

Grouped place attributes.

related_places

optional

object[]

When related places are present.

Related places from Maps payload.

short_description

optional

string

When description block is present.

Short place description.

description

optional

string

When description block is present.

Longer place description.

snippet

optional

string

short_description or description fallback.

Normalized text summary.

timezone

optional

string

When present.

Place timezone.

region

optional

string

When present.

Region label.

country_code

optional

string

When present.

Country code.

language

optional

string

When present.

Language code from Maps payload.

Code and response examples

bash

curl -X POST 'https://api.serpbase.dev/google/maps/search' \
  -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"location":{"location_query":"Seattle, WA"},"query":"coffee"}'

Existing Google request example

bash

curl -X POST https://api.serpbase.dev/google/maps/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "q": "coffee",
    "hl": "en",
    "gl": "us",
    "page": 1,
    "lat": 37.7749,
    "lng": -122.4194,
    "zoom": 14
  }'

Notes

Local discovery, store lookup, geo-targeted auditing.

lat and lng must be sent together. zoom is valid only with coordinates and defaults to 14.