Home/API Documentation

API Documentation

Complete reference for all SERP Search API endpoints.

Quick Start

Get up and running in three steps:

Generate an API key from your dashboard.

Make your first request:

# 1. Set your API key
API_KEY="mk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

# 2. Make your first search
curl -G https://serpsearch.com/api/v1/search \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "query=web scraping best practices"

# 3. The response is JSON with organic_results, knowledge_graph, etc.

Authentication

All requests must include a valid API key as a Bearer token in the Authorization header.

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx

You can generate API keys from your dashboard. Keys are tied to your subscription and track usage against your monthly quota.

Important: Keep your API key secret. Do not expose it in client-side code or public repositories. If you suspect a key has been compromised, revoke it immediately from your dashboard and generate a new one.

Web Search

Method	URL
GET	`https://serpsearch.com/api/v1/search`

Parameters

Name	Type	Required	Default	Description
`query`	string	Yes	--	The search query.
`page`	integer	No	`1`	Results page number (1-based, 10 results per page).
`lat`	number	No	--	Latitude for geo-targeted results.
`lng`	number	No	--	Longitude for geo-targeted results.
`location`	string	No	--	Location string for geo-targeting (e.g. "New York, NY, US").
`response_type`	string	No	`json`	Response format: json, html, both, or correlated.
`js`	boolean	No	`false`	When true, keeps JavaScript in HTML response; when false, strips script tags.

Response

{
  "search_info": {
    "total_results": "About 1,230,000 results",
    "time_taken": "0.42 seconds"
  },
  "organic_results": [
    {
      "title": "OpenAI",
      "url": "https://openai.com",
      "website": "openai.com",
      "position": 1,
      "description": "An AI research company...",
      "visible_url": "openai.com",
      "answer": null,
      "date": null,
      "thumbnail": null
    }
  ],
  "knowledge_graph": { "title": "...", "description": "...", ... },
  "definition_result": null,
  "people_also_ask": [{ "question": "What is OpenAI?" }],
  "weather_result": null,
  "related_searches": [{ "query": "openai competitors" }],
  "local_results": null,
  "top_stories": null
}

Example

curl -G "https://serpsearch.com/api/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=latest AI models" \
  -d "page=1"

Autocomplete

Method	URL
GET	`https://serpsearch.com/api/v1/autocomplete`

Parameters

Name	Type	Required	Default	Description
`query`	string	Yes	--	The search query to get suggestions for.
`lat`	number	No	--	Latitude for geo-targeted suggestions.
`lng`	number	No	--	Longitude for geo-targeted suggestions.
`location`	string	No	--	Location string for geo-targeted suggestions.

Response

[
  {
    "title": "openai chatgpt",
    "additional_info": {
      "title": "ChatGPT",
      "description": "AI chatbot by OpenAI",
      "image": "https://..."
    }
  },
  {
    "title": "openai api"
  }
]

Example

curl -G "https://serpsearch.com/api/v1/autocomplete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=openai"

Translation

Method	URL
GET	`https://serpsearch.com/api/v1/translate`

Parameters

Name	Type	Required	Default	Description
`query`	string	Yes	--	The text to translate.
`lang`	string	No	`en`	Target language code (e.g. en, es, fr, de, ja).

Response

{
  "translation": "Hello world",
  "sentences": [
    {
      "original": "Hola mundo",
      "translation": "Hello world"
    }
  ]
}

Example

curl -G "https://serpsearch.com/api/v1/translate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=Hola mundo" \
  -d "lang=en"

News

Method	URL
GET	`https://serpsearch.com/api/v1/news`

Parameters

Name	Type	Required	Default	Description
`query`	string	Yes	--	The news search query.
`lat`	number	No	--	Latitude for geo-targeted results.
`lng`	number	No	--	Longitude for geo-targeted results.
`location`	string	No	--	Location string for geo-targeted results.

Response

[
  {
    "group_name": "Top stories",
    "articles": [
      {
        "title": "OpenAI announces new model",
        "url": "https://example.com/article",
        "created_at": 1705312200
      }
    ]
  }
]

Example

curl -G "https://serpsearch.com/api/v1/news" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=artificial intelligence"

Image Search

Method	URL
GET	`https://serpsearch.com/api/v1/images`

Parameters

Name	Type	Required	Default	Description
`query`	string	Yes	--	The image search query.
`page`	integer	No	`1`	Results page number (20 results per page).
`lat`	number	No	--	Latitude for geo-targeted results.
`lng`	number	No	--	Longitude for geo-targeted results.
`location`	string	No	--	Location string for geo-targeted results.

Response

[
  {
    "title": "AI Generated Art",
    "url": "https://example.com/page",
    "source": "example.com",
    "alt": "AI generated artwork",
    "is_licensable": false,
    "preview": {
      "url": "https://example.com/thumb.jpg",
      "width": 300,
      "height": 200
    },
    "full": {
      "url": "https://example.com/full.jpg",
      "width": 1920,
      "height": 1080
    }
  }
]

Example

curl -G "https://serpsearch.com/api/v1/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=sunset photography" \
  -d "page=1"

Video Search

Method	URL
GET	`https://serpsearch.com/api/v1/videos`

Parameters

Name	Type	Required	Default	Description
`query`	string	Yes	--	The video search query.
`page`	integer	No	`1`	Results page number (10 results per page).
`lat`	number	No	--	Latitude for geo-targeted results.
`lng`	number	No	--	Longitude for geo-targeted results.
`location`	string	No	--	Location string for geo-targeted results.

Response

[
  {
    "title": "Introduction to Machine Learning",
    "url": "https://youtube.com/watch?v=...",
    "description": "A beginner-friendly guide...",
    "thumbnail": "https://i.ytimg.com/vi/.../default.jpg",
    "duration": "12:34",
    "website": "youtube.com",
    "channel_name": "Tech Channel",
    "upload_date": "2024-01-10"
  }
]

Example

curl -G "https://serpsearch.com/api/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=machine learning tutorial" \
  -d "page=1"

Maps Search

Method	URL
GET	`https://serpsearch.com/api/v1/maps`

Parameters

Name	Type	Required	Default	Description
`query`	string	Yes	--	The maps search query (e.g. business name, category).
`lat`	number	No	--	Latitude for geo-targeted results.
`lng`	number	No	--	Longitude for geo-targeted results.
`location`	string	No	--	Location string for geo-targeted results.

Response

{
  "results": [
    {
      "name": "Central Park",
      "address": "New York, NY 10024",
      "rating": 4.8,
      "review_count": 120000,
      "price_range": null,
      "price_description": null,
      "place_id": "ChIJ4zGFAZpYwokRGUGph3Mf37k",
      "feature_id": "0x89c2589a0185...",
      "logo": null,
      "link": null,
      "lat": 40.7829,
      "lng": -73.9654,
      "opening_hours": ["Open 24 hours"],
      "rating_distribution": { "5": 90000, "4": 20000, "3": 5000, "2": 3000, "1": 2000 }
    }
  ]
}

Example

curl -G "https://serpsearch.com/api/v1/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=coffee shops in manhattan"

Place Details

Method	URL
GET	`https://serpsearch.com/api/v1/maps/place`

Parameters

Name	Type	Required	Default	Description
`feature_id`	string	Yes	--	The feature ID from a maps search result's feature_id field.

Response

{
  "name": "Central Park",
  "address": "New York, NY 10024",
  "rating": 4.8,
  "review_count": 120000,
  "price_range": null,
  "price_description": null,
  "place_id": "ChIJ4zGFAZpYwokRGUGph3Mf37k",
  "feature_id": "0x89c2589a0185...",
  "logo": null,
  "link": null,
  "lat": 40.7829,
  "lng": -73.9654,
  "opening_hours": ["Open 24 hours"],
  "rating_distribution": { "5": 90000, "4": 20000, "3": 5000, "2": 3000, "1": 2000 }
}

Example

curl -G "https://serpsearch.com/api/v1/maps/place" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "feature_id=0x89c2589a0185..."

Distance

Method	URL
GET	`https://serpsearch.com/api/v1/maps/distance`

Parameters

Name	Type	Required	Default	Description
`from_lat`	number	Yes	--	Starting point latitude.
`from_lng`	number	Yes	--	Starting point longitude.
`to_lat`	number	Yes	--	Destination latitude.
`to_lng`	number	Yes	--	Destination longitude.

Response

{
  "distance_text": "5.2 mi",
  "duration_text": "15 mins",
  "distance_meters": 8368
}

Example

curl -G "https://serpsearch.com/api/v1/maps/distance" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "from_lat=40.758" -d "from_lng=-73.9855" \
  -d "to_lat=40.7829" -d "to_lng=-73.9654"

Reviews

Method	URL
GET	`https://serpsearch.com/api/v1/reviews`

Parameters

Name	Type	Required	Default	Description
`place_id`	string	Yes	--	The Google Place ID to fetch reviews for.
`sort_by`	string	No	`relevant`	Sort order: relevant, newest, high_rating, or low_rating.
`page_id`	string	No	--	Pagination token from a previous response's next_page field.
`search`	string	No	--	Filter reviews by keyword.
`lat`	number	No	--	Latitude for geo-targeting.
`lng`	number	No	--	Longitude for geo-targeting.
`location`	string	No	--	Location string for geo-targeting.

Response

{
  "reviews": [
    {
      "review": {
        "id": "abc123",
        "rating": 5,
        "text": "Amazing place, highly recommend!",
        "translated_text": null,
        "lang": "en",
        "created_at": 1704873600,
        "updated_at": null,
        "link": "https://..."
      },
      "user": {
        "id": "1234567890",
        "name": "John D.",
        "image_url": "https://...",
        "review_count": 42,
        "profile_url": "https://..."
      },
      "response": {
        "text": "Thank you for your kind words!",
        "translated_text": null,
        "lang": "en",
        "created_at": 1704960000
      }
    }
  ],
  "next_page": "eyJwYWdlIjoyf..."
}

Example

curl -G "https://serpsearch.com/api/v1/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "place_id=ChIJ4zGFAZpYwokRGUGph3Mf37k" \
  -d "sort_by=newest"

Error Codes

All errors follow the same envelope shape:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please slow down your requests."
  }
}

Code	HTTP	Description
`INVALID_API_KEY`	401	The API key is missing, malformed, or does not exist.
`EXPIRED_API_KEY`	401	The API key has passed its expiration date.
`REVOKED_API_KEY`	401	The API key has been manually revoked.
`SUBSCRIPTION_REQUIRED`	403	No active subscription found for this account.
`SUBSCRIPTION_INACTIVE`	403	The subscription exists but is not in ACTIVE state.
`RATE_LIMIT_EXCEEDED`	429	More than the allowed requests per second were sent. Slow down and retry.
`QUOTA_EXCEEDED`	429	Monthly request quota for the current billing period is exhausted.
`INVALID_QUERY`	400	The q / query parameter is missing, empty, or the request body is malformed JSON.
`UPSTREAM_ERROR`	502	The upstream search provider returned an error. Retry later.
`INTERNAL_ERROR`	500	An unexpected server-side error occurred.

Rate Limits & Quotas

Two separate limits apply to every request:

Per-second rate limit -- enforced with a sliding window. Exceeding it returns RATE_LIMIT_EXCEEDED (HTTP 429) with a Retry-After: 1 header.
Monthly quota -- resets with your billing period. Exceeding it returns QUOTA_EXCEEDED (HTTP 429). Upgrade your plan to increase your limit.

Plan	Monthly requests	Requests / second	Price
Starter	40,000	5	$40 / mo
Pro	400,000	15	$300 / mo
Business	1,500,000	50	$1,000 / mo
Enterprise	Custom	Custom	Contact us

You can monitor your current usage from the usage dashboard. Need higher limits? View all plans or contact us for Enterprise pricing.

Response Headers

Every response (including errors) includes the following headers to help you track your usage and rate limits:

Header	Description
`X-RateLimit-Limit`	Maximum requests per second allowed for your plan.
`X-RateLimit-Remaining`	Requests remaining in the current one-second window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the rate limit window resets.
`X-Quota-Used`	Total requests used in the current billing period.
`X-Quota-Limit`	Total requests allowed in the current billing period.
`X-Response-Time`	End-to-end server processing time (e.g. `142ms`). Only present on successful responses.
`Retry-After`	Seconds to wait before retrying. Present only on `RATE_LIMIT_EXCEEDED` responses.

Ready to get started?

Create a free account, pick a plan, and generate your API key in minutes.