Google Search (SERP)
Search the web through AceDataCloud's Google SERP API.
Setup: See authentication for token setup.
Quick Start
curl -X POST https://api.acedata.cloud/serp/google \
-H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "latest AI news", "type": "search"}'
Search Types
| Type |
Description |
Returns |
search |
Web search (default) |
Organic results, knowledge graph, rich snippets |
images |
Image search |
Image URLs, titles, sources |
news |
News articles |
Headlines, sources, publish dates |
maps |
Map results |
Locations, coordinates |
places |
Local businesses/places |
Name, address, rating, reviews |
videos |
Video results |
Video URLs, thumbnails, duration |
Parameters
POST /serp/google
{
"query": "your search query",
"type": "search",
"country": "us",
"language": "en",
"range": "qdr:w",
"number": 10,
"page": 1
}
| Parameter |
Type |
Description |
query |
string |
Search query (required; must contain non-whitespace text; maximum 2048 characters) |
type |
string |
One of: search, images, news, maps, places, videos |
country |
string |
Non-empty country code (e.g., "us", "uk", "cn", "jp"; maximum 32 characters) |
language |
string |
Non-empty language code (e.g., "en", "zh", "ja"; maximum 32 characters) |
range |
string |
Time filter (see below) |
number |
int |
Number of results per page |
page |
int |
Page number for pagination |
image_size |
string |
Images only. Filter by size for high-res sources: large / medium / icon, or a megapixel minimum 2mp…70mp (e.g. 4mp = larger than 4 megapixels). Use large (or a *mp value) whenever the image will be shown large / full-screen / zoomed. |
Time Range Options
| Value |
Period |
qdr:h |
Past hour |
qdr:d |
Past 24 hours |
qdr:w |
Past week |
qdr:m |
Past month |
qdr:y |
Past year |
h |
Past hour |
d |
Past 24 hours |
w |
Past week |
m |
Past month |
y |
Past year |
Response Structure
Web search returns structured data including:
organic_results: Main search results with title, link, snippetknowledge_graph: Entity information panel (when available)related_searches: Related query suggestions
Gotchas
- Default search type is
"search" (web). Always specify type for non-web searches
- Country and language codes affect result localization significantly
number controls results per page, not total results — use page for pagination- Time range (
range) only applies to web search and news, not images or places
- Image resolution (important for video / full-screen use): results include
image_url (full-size), thumbnail_url, and image_width/image_height. Pass image_size: "large" (or a megapixel minimum like "4mp") to get sharp sources, and pick the result with the largest image_width×image_height. Always download image_url — never use thumbnail_url as a final asset (it is tiny and blurry).
- Places search works best with location-specific queries (e.g., "restaurants near Times Square")
MCP: pip install mcp-serp | Hosted: https://serp.mcp.acedata.cloud/mcp | See all MCP servers
1---
2name: google-search
3description: Search the web using Google via AceDataCloud API. Use when searching for web pages, images, news, maps, local places, or videos. Supports localization, time filtering, and pagination. Returns structured results with titles, snippets, URLs, and rich data.
4license: Apache-2.0
5metadata:
6 author: acedatacloud
7 version: "1.0"
8compatibility: Requires ACEDATACLOUD_API_TOKEN in .env file (see _shared/authentication.md). Optionally pair with mcp-serp for tool-use.
9---
10
11# Google Search (SERP)
12
13Search the web through AceDataCloud's Google SERP API.
14
15> **Setup:** See [authentication](../_shared/authentication.md) for token setup.
16
17## Quick Start
18
19```bash
20curl -X POST https://api.acedata.cloud/serp/google \
21 -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
22 -H "Content-Type: application/json" \
23 -d '{"query": "latest AI news", "type": "search"}'
24```
25
26## Search Types
27
28| Type | Description | Returns |
29|------|-------------|---------|
30| `search` | Web search (default) | Organic results, knowledge graph, rich snippets |
31| `images` | Image search | Image URLs, titles, sources |
32| `news` | News articles | Headlines, sources, publish dates |
33| `maps` | Map results | Locations, coordinates |
34| `places` | Local businesses/places | Name, address, rating, reviews |
35| `videos` | Video results | Video URLs, thumbnails, duration |
36
37## Parameters
38
39```json
40POST /serp/google
41{
42 "query": "your search query",
43 "type": "search",
44 "country": "us",
45 "language": "en",
46 "range": "qdr:w",
47 "number": 10,
48 "page": 1
49}
50```
51
52| Parameter | Type | Description |
53|-----------|------|-------------|
54| `query` | string | Search query (required; must contain non-whitespace text; maximum 2048 characters) |
55| `type` | string | One of: search, images, news, maps, places, videos |
56| `country` | string | Non-empty country code (e.g., "us", "uk", "cn", "jp"; maximum 32 characters) |
57| `language` | string | Non-empty language code (e.g., "en", "zh", "ja"; maximum 32 characters) |
58| `range` | string | Time filter (see below) |
59| `number` | int | Number of results per page |
60| `page` | int | Page number for pagination |
61| `image_size` | string | **Images only.** Filter by size for high-res sources: `large` / `medium` / `icon`, or a megapixel minimum `2mp`…`70mp` (e.g. `4mp` = larger than 4 megapixels). Use `large` (or a `*mp` value) whenever the image will be shown large / full-screen / zoomed. |
62
63## Time Range Options
64
65| Value | Period |
66|-------|--------|
67| `qdr:h` | Past hour |
68| `qdr:d` | Past 24 hours |
69| `qdr:w` | Past week |
70| `qdr:m` | Past month |
71| `qdr:y` | Past year |
72| `h` | Past hour |
73| `d` | Past 24 hours |
74| `w` | Past week |
75| `m` | Past month |
76| `y` | Past year |
77
78## Response Structure
79
80Web search returns structured data including:
81- `organic_results`: Main search results with title, link, snippet
82- `knowledge_graph`: Entity information panel (when available)
83- `related_searches`: Related query suggestions
84
85## Gotchas
86
87- Default search type is `"search"` (web). Always specify `type` for non-web searches
88- Country and language codes affect result localization significantly
89- `number` controls results per page, not total results — use `page` for pagination
90- Time range (`range`) only applies to web search and news, not images or places
91- **Image resolution (important for video / full-screen use):** results include `image_url` (full-size), `thumbnail_url`, and `image_width`/`image_height`. Pass **`image_size: "large"`** (or a megapixel minimum like `"4mp"`) to get sharp sources, and pick the result with the largest `image_width`×`image_height`. Always download `image_url` — **never** use `thumbnail_url` as a final asset (it is tiny and blurry).
92- Places search works best with location-specific queries (e.g., "restaurants near Times Square")
93
94> **MCP:** `pip install mcp-serp` | Hosted: `https://serp.mcp.acedata.cloud/mcp` | See [all MCP servers](../_shared/mcp-servers.md)
acedatacloud