OpenAPI Specification
openapi: 3.0.3
info:
title: Serper Google Search Autocomplete Maps API
description: RESTful API providing real-time Google Search Engine Results Page (SERP) data in structured JSON format. Supports web search, image search, news, maps, places, videos, shopping, scholar, patents, and autocomplete via POST endpoints. Authentication uses an X-API-KEY header. Designed for high-throughput AI and LLM applications with up to 300 queries per second.
version: 1.0.0
contact:
name: Serper Support
url: https://serper.dev
termsOfService: https://serper.dev/terms-of-service
license:
name: Commercial
url: https://serper.dev
servers:
- url: https://google.serper.dev
description: Serper API server
security:
- apiKeyHeader: []
tags:
- name: Maps
description: Maps and location search
paths:
/maps:
post:
operationId: mapsSearch
summary: Maps Search
description: Perform a Google Maps search returning local business and place data with coordinates, ratings, addresses, and contact information.
tags:
- Maps
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MapsRequest'
example:
q: coffee shops
ll: '@40.7504178,-73.9824837,14z'
gl: us
hl: en
responses:
'200':
description: Successful maps search response
content:
application/json:
schema:
$ref: '#/components/schemas/MapsSearchResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
SearchParameters:
type: object
properties:
q:
type: string
description: The search query.
gl:
type: string
description: Country code.
hl:
type: string
description: Language code.
type:
type: string
description: The type of search performed.
num:
type: integer
description: Number of results requested.
page:
type: integer
description: Page number.
MapsSearchResponse:
type: object
properties:
searchParameters:
$ref: '#/components/schemas/SearchParameters'
ll:
type: string
description: Coordinates and zoom used for the maps search.
places:
type: array
description: Place results.
items:
$ref: '#/components/schemas/PlaceResult'
SearchRequest:
type: object
required:
- q
properties:
q:
type: string
description: The search query string.
example: google search
gl:
type: string
description: Country code for geolocation of results (ISO 3166-1 alpha-2).
example: us
default: us
hl:
type: string
description: Language code for results (ISO 639-1).
example: en
default: en
num:
type: integer
description: Number of results to return (1-100).
minimum: 1
maximum: 100
default: 10
example: 10
page:
type: integer
description: Page number for pagination.
minimum: 1
default: 1
example: 1
tbs:
type: string
description: Time-based search filter. Use values like 'qdr:h' (past hour), 'qdr:d' (past day), 'qdr:w' (past week), 'qdr:m' (past month), 'qdr:y' (past year).
example: qdr:d
autocorrect:
type: boolean
description: Whether to enable autocorrect for the query.
default: true
PlaceResult:
type: object
properties:
position:
type: integer
description: Position in results.
title:
type: string
description: Name of the place or business.
address:
type: string
description: Full street address.
latitude:
type: number
format: double
description: Latitude coordinate.
longitude:
type: number
format: double
description: Longitude coordinate.
rating:
type: number
format: float
description: Average rating (1-5).
ratingCount:
type: integer
description: Number of ratings.
type:
type: string
description: Primary business type/category.
types:
type: array
items:
type: string
description: List of all business types/categories.
website:
type: string
format: uri
description: Business website URL.
phoneNumber:
type: string
description: Contact phone number.
description:
type: string
description: Business description.
category:
type: string
description: Business category.
cid:
type: string
description: Google Customer ID for the place.
ErrorResponse:
type: object
properties:
message:
type: string
description: Human-readable error description.
MapsRequest:
allOf:
- $ref: '#/components/schemas/SearchRequest'
- type: object
properties:
ll:
type: string
description: 'Latitude/longitude coordinates and zoom level for maps search. Format: @{lat},{lng},{zoom}z'
example: '@40.7504178,-73.9824837,14z'
responses:
Unauthorized:
description: Unauthorized — invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
TooManyRequests:
description: Too many requests — rate limit exceeded or credits exhausted.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Bad request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
apiKeyHeader:
type: apiKey
in: header
name: X-API-KEY
description: API key obtained from https://serper.dev/api-key