Documentation
Choose a search API below. Each page has its own examples and field reference; authentication and account endpoints are covered here.
OpenAPI specification: Download YAML
Search APIs
- Google Search API
- Google Autocomplete API
- Google Images API
- Google Videos API
- Google News API
- Google Shopping API
- Google Forums API
- Google Books API
- Google Maps API
- Google Patents API
Bing
Before you start
Create an API key in the console, then set SERP_API_KEY to your key.
export SERP_API_KEY='YOUR_API_KEY'
Authentication
Pass your API key in the x-api-key header. Keys are created in the console and shown only once.
x-api-key: YOUR_API_KEY Do not put keys in URL query strings. Keep them server-side.
Official client SDKs
Integrate Serqo directly into your applications using our zero-dependency official language clients:
| Language | Package & Install | Quick start |
|---|---|---|
| JavaScript / TypeScript | npm install serqo-sdk | import { Serqo } from 'serqo-sdk'; |
| Python | pip install serqo | from serqo import Serqo |
| PHP | composer require serqo-io/serqo-php | use Serqo\Client; |
| Go | go get github.com/serqo-io/serqo-go | import "github.com/serqo-io/serqo-go" |
| Java | io.serqo:serqo-java | import io.serqo.sdk.SerqoClient; |
| Ruby | gem install serqo | require 'serqo' |
Use with AI coding assistants (Cursor, Claude, Copilot)
Give your AI assistant the exact specifications, official SDK patterns, and parsing rules to implement search features in one shot:
.cursorrules) Download directly to your repository root or copy the full prompt:
curl -o .cursorrules https://serqo.io/.cursorrules
SKILL.md / Claude Code) Equip autonomous AI agents with live Google and Bing search capabilities. See our LangChain & AI Agents Guide for Python examples:
curl -o SKILL.md https://serqo.io/SKILL.md
Paste into ChatGPT or Claude to initialize a new search integration from scratch:
I want to integrate search engine results into my project using the Serqo Search API (https://serqo.io).
API Details:
- Endpoint: POST https://api.serqo.io/v1/search
- Autocomplete: GET/POST https://api.serqo.io/v1/autocomplete
- Authentication Header: x-api-key: <SERP_API_KEY>
- Content-Type: application/json
- Supported Engines: "google", "bing"
- Supported Types:
- Google: "web", "news", "maps", "images", "videos", "shopping", "forums", "books", "patents"
- Bing: "web", "news", "maps", "images", "videos"
- Standard Parameters: q (string, required), engine (string), type (string), gl (country code, e.g. "us"), hl (language code, e.g. "en"), tbs (Google time filter, e.g. "qdr:d" or "qdr:w"), start (integer offset).
Official Client SDKs:
- Python: `pip install serqo` -> `from serqo import Serqo; client = Serqo(api_key=...)`
- Node.js / TypeScript: `npm install serqo-sdk` -> `import { Serqo } from 'serqo-sdk'; const client = new Serqo({ apiKey: ... })`
- PHP: `composer require serqo-io/serqo-php` -> `use Serqo\Client; $client = new Client(...)`
Response Structure:
The API returns a JSON envelope:
{
"success": true,
"requestId": "...",
"data": {
"engine": "google",
"type": "web",
"results": [
{ "position": 1, "title": "...", "url": "...", "domain": "...", "snippet": "..." }
],
"features": {
"localResults": [ ... ]
},
"pagination": {
"hasNext": true,
"nextStart": 10
}
}
}
My Requirements:
[Describe your feature requirements here: language/framework, use case, and target engines/types].
Please write the complete, production-ready implementation, including error handling (retrying HTTP 429 with backoff) and clean JSON parsing. Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /v1/search | Run a search. Set type to choose the search type. |
| POST / GET | /v1/autocomplete | Real-time search suggestions and multi-round SEO keyword expansion. |
| GET | /v1/engines | List engines and their supported search types. |
| GET | /v1/me | The account and key making the request. |
| GET | /v1/health | API health check. No API key required; does not test search engines. |
Supported search types
Choose a search type with type. Omit it for a web search. Google supports all nine types below; Bing supports web, news, images, videos and maps. A dash means the engine does not support that type.
Call GET /v1/engines with your API key to check available engines and their verticals before sending a search. Types temporarily under maintenance are omitted.
| Search type | Request value | Bing | |
|---|---|---|---|
| Web | web | ✓ | ✓ |
| News | news | ✓ | ✓ |
| Images | images | ✓ | ✓ |
| Videos | videos | ✓ | ✓ |
| Maps | maps | ✓ | ✓ |
| Shopping | shopping | ✓ | — |
| Forums | forums | ✓ | — |
| Books | books | ✓ | — |
| Patents | patents | ✓ | — |
GET /v1/engines
List available search engines and the search types each supports. Use the engine id and a supported vertical in your search request.
API key required. No query parameters or request body needed.
Request example
curl https://api.serqo.io/v1/engines \ -H "x-api-key: $SERP_API_KEY"
200 response
{
"success": true,
"requestId": "req_example",
"data": {
"engines": [
{
"id": "google",
"displayName": "Google",
"verticals": [
"web",
"images",
"videos",
"news",
"shopping",
"forums",
"books",
"maps",
"patents"
],
"pagination": "start"
},
{
"id": "bing",
"displayName": "Bing",
"verticals": [
"web",
"news",
"images",
"videos",
"maps"
],
"pagination": "start"
}
]
}
} | Response path | Type | Contents |
|---|---|---|
| data.engines | array | Available engines. |
| data.engines[].id | string | Value to pass as engine. |
| data.engines[].displayName | string | Engine name for display. |
| data.engines[].verticals | string[] | Allowed type values for this engine. |
| data.engines[].pagination | string | Pagination method, currently start. |
This request does not consume search credits. Invalid keys return 401; engine-list failures can return 5xx.
GET /v1/me
Check which account and API key are making the request. The response does not include the full API key or credit balance.
API key required. No query parameters or request body needed.
Request example
curl https://api.serqo.io/v1/me \ -H "x-api-key: $SERP_API_KEY"
200 response
{
"success": true,
"requestId": "req_example",
"data": {
"account": {
"id": "account_example",
"email": "developer@example.com",
"role": "user"
},
"key": {
"id": "key_example",
"prefix": "sk_example"
}
}
} | Response path | Type | Contents |
|---|---|---|
| data.account.id | string | Account ID. |
| data.account.email | string | Account email. |
| data.account.role | string | Role assigned to this account. |
| data.key.id | string | ID of the API key used. |
| data.key.prefix | string | Key prefix for identifying the key. |
Example account values are illustrative. This request does not consume search credits. An invalid, revoked or expired key returns 401 UNAUTHORIZED.
GET /v1/health
Check whether the API service responds. This does not test search engines, account access or available credits.
No API key, query parameters or request body needed.
Request example
curl https://api.serqo.io/v1/health
200 response
{
"success": true,
"data": {
"status": "ok"
}
} data.status is ok when the service responds. This endpoint does not use the usual requestId response body. It does not consume search credits.
Errors
Check the error reason and retry guidance when a search fails. Provide the request ID when troubleshooting.
{
"success": false,
"requestId": "req_01H…",
"error": {
"code": "INVALID_PARAM",
"message": "Invalid search parameter",
"retryable": false
}
} Common errors
- 400 · BAD_REQUEST
- Check that the request is valid JSON and includes a non-empty query.
- 400 · UNSUPPORTED_VERTICAL
- Choose a search type supported by the selected engine.
- 503 · SEARCH_TYPE_UNAVAILABLE
- This search type is temporarily unavailable while it is under maintenance. Retry later.
- 400 · GEO_CONFLICT
- The requested region conflicts with the search connection. Check the country code and provide the request ID if the error persists.
- 401 · UNAUTHORIZED
- Provide an active, unexpired API key for an active account. Invalid, revoked and expired keys return UNAUTHORIZED.
- 402 · INSUFFICIENT_CREDITS
- Your available balance cannot cover the request.
- 422 · INVALID_PARAM
- Check the parameter name, type and allowed values.
- 429 · QUOTA_EXCEEDED / QUEUE_FULL
- For QUOTA_EXCEEDED, wait for retryAfterMs before retrying. QUEUE_FULL also returns 429; follow its retry guidance.
- 502/503/504
- Upstream failures are not charged. Follow the response’s retry guidance.
- 500 · INTERNAL_ERROR
- Keep the request ID for troubleshooting.
Check the HTTP status before reading JSON. Network failures and responses from a proxy may not contain the API error body. Preserve the request ID when one is available.
Retry only when error.retryable is true. If error.retryAfterMs is present, wait at least that many milliseconds. To safely retry after a lost response, send the same Idempotency-Key with the same parameters; the original successful response is replayed without another search or charge for 24 hours. Without that header, a retry is a new request and uses the applicable credit rate.
The request ID is available in the response body and the x-request-id response header.
Rate limits and credits
Rate limits
Each API key is limited by the account’s requests-per-second allowance. Playground sessions are counted separately. A 429 response includes the wait time in milliseconds; wait before retrying.
Credit usage
Cost depends on search type, engine, country and cache status. Failed searches and timeouts are not charged. View your available balance and credit history in Plan and credits.
Cache hits are free at the default rate. Before a search starts, your available balance must cover the full request cost, even if the result later comes from cache.