OpenAPI Specification
openapi: 3.0.3
info:
title: Serper Google Search Autocomplete Places 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: Places
description: Local business and place search
paths:
/places:
post:
operationId: placesSearch
summary: Places Search
description: Perform a Google Places search returning detailed local business information including addresses, ratings, categories, phone numbers, and websites.
tags:
- Places
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MapsRequest'
example:
q: restaurants near me
gl: us
hl: en
responses:
'200':
description: Successful places search response
content:
application/json:
schema:
$ref: '#/components/schemas/PlacesSearchResponse'
'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.
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'
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.
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
ErrorResponse:
type: object
properties:
message:
type: string
description: Human-readable error description.
PlacesSearchResponse:
type: object
properties:
searchParameters:
$ref: '#/components/schemas/SearchParameters'
places:
type: array
description: Place search results.
items:
$ref: '#/components/schemas/PlaceResult'
responses:
Unauthorized:
description: Unauthorized — invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Bad request — missing or invalid parameters.
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'
securitySchemes:
apiKeyHeader:
type: apiKey
in: header
name: X-API-KEY
description: API key obtained from https://serper.dev/api-key