API Documentation

Quick Start

Get up and running in a few steps:

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

# 2. Make your first search
curl -G https://api.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 gt_live_xxxxxxxxxxxxxxxxxxxxxxxx

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

Web Search

Parameters

Response

{
  "search_info": {
    "total_results": "About 21,600,000 results",
    "time_taken": "0.29 seconds"
  },
  "organic_results": [
    {
      "title": "Beautiful Soup: Build a Web Scraper With Python",
      "url": "https://realpython.com/beautiful-soup-web-scraper-python/",
      "website": "Real Python",
      "position": 1,
      "description": "Learn how to scrape web pages and parse HTML with Beautiful Soup.",
      "visible_url": "https://realpython.com › beautiful-soup-web-scraper-python",
      "sitelinks": [
        {
          "title": "Parse HTML",
          "url": "https://realpython.com/beautiful-soup-web-scraper-python/#parse-html",
          "description": "Inspect and extract structured content."
        }
      ]
    }
  ],
  "knowledge_graph": {
    "title": "Beautiful Soup",
    "category": "Python library",
    "description": "A Python package for parsing HTML and XML documents.",
    "source_name": "Wikipedia",
    "source_link": "https://en.wikipedia.org/wiki/Beautiful_Soup_(HTML_parser)",
    "facts": [
      {
        "key": "initial release",
        "value": "2004"
      }
    ]
  },
  "ai_overview": {
    "answer": "Beautiful Soup parses HTML into a tree that Python code can search and traverse.",
    "citations": [
      {
        "title": "Beautiful Soup documentation",
        "url": "https://www.crummy.com/software/BeautifulSoup/bs4/doc/"
      }
    ]
  }
}

Example

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

Search Response Schema

Autocomplete

Parameters

Response

[
  {
    "title": "python web scraping"
  },
  {
    "title": "python web scraping library"
  },
  {
    "title": "python web scraping cookbook",
    "additional_info": {
      "title": "Python Web Scraping Cookbook",
      "description": "Book by Michael Heydt",
      "image": "https://..."
    }
  }
]

Example

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

Translation

Parameters

Response

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

Example

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

News

Parameters

Response

[
  {
    "group_name": "Ungrouped",
    "articles": [
      {
        "title": "February 2026 Google Discover Core Update Is Done Rolling Out",
        "url": "https://www.seroundtable.com/february-2026-google-discover-core-update-done.html",
        "created_at": 1772188980
      },
      {
        "title": "Google's Discover Core Update Finishes Rolling Out",
        "url": "https://www.searchenginejournal.com/googles-discover-core-update-finishes/568413/",
        "created_at": 1772198715
      }
    ]
  }
]

Example

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

Image Search

Parameters

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://api.serpsearch.com/api/v1/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=sunset photography" \
  -d "page=1"

Video Search

Parameters

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://api.serpsearch.com/api/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=machine learning tutorial" \
  -d "page=1"

Maps Search

Parameters

Response

{
  "results": [
    {
      "name": "Google France",
      "address": "Google France, 8 Rue de Londres, 75009 Paris, France",
      "rating": 4.1,
      "place_id": "ChIJixLu7DBu5kcRQnIpA2tErS8",
      "feature_id": "0x47e66e30ecee128b:0x2fad446b03297242",
      "website": "http://google.com/",
      "lat": 48.8775,
      "lng": 2.3300,
      "timezone": "Europe/Paris",
      "country_code": "FR",
      "categories": ["Corporate office", "Software company"],
      "opening_hours": ["Friday: 9:30 am–7:30 pm"]
    }
  ]
}

Example

curl -G "https://api.serpsearch.com/api/v1/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=google offices in paris"

Place Details

Parameters

Response

{
  "name": "Auto Urgnano srl",
  "address": "Auto Urgnano srl, Via Leon Battista Alberti, 18, 24059 Urgnano BG, Italy",
  "rating": 4.4,
  "review_count": 115,
  "place_id": "ChIJE4BAyxZFgUcRrOjaYjiUOI4",
  "feature_id": "0x47814516cb408013:0x8e38943862dae8ac",
  "logo": "https://streetviewpixels-pa...",
  "link": "https://www.google.com/maps/place/?q=place_id:ChIJE4BAyxZFgUcRrOjaYjiUOI4",
  "lat": 45.5898,
  "lng": 9.7016,
  "timezone": "Europe/Rome",
  "country_code": "IT",
  "categories": ["Used car dealer"],
  "opening_hours": ["Friday: 9 am–6:30 pm", "Saturday: 9 am–4 pm", "Sunday: Closed"],
  "rating_distribution": { "5": 91, "4": 7, "3": 1, "2": 5, "1": 11 }
}

Example

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

Distance

Parameters

Response

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

Example

curl -G "https://api.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

Parameters

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://api.serpsearch.com/api/v1/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "place_id=0x47814516cb408013:0x8e38943862dae8ac" \
  -d "sort_by=newest"

Review Batch Exports (Pro+)

Export Google Maps reviews asynchronously across a specific creation date range. This API is available to active Pro, Business, and Enterprise subscriptions. It is designed for jobs that may span many review pages and returns a private, gzipped NDJSON file instead of holding a long-running HTTP connection open.

Endpoints

Create an export

Send a JSON body to POST https://api.serpsearch.com/api/v1/reviews/batches. A new job returns 202 Accepted. Reusing the same Idempotency-Key for the account returns the original job with 200 OK, so retrying a timed-out create request does not enqueue a duplicate.

JSON body

Creation example

curl -X POST "https://api.serpsearch.com/api/v1/reviews/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: apple-reviews-2026-08" \
  --data '{
    "featureId": "0x808fbb38fa3f36f9:0xf5692002b984147",
    "startAt": "2026-08-01T00:00:00Z",
    "endAt": "2026-08-20T00:00:00Z",
    "hl": "en",
    "gl": "us"
  }'

Job response

{
  "id": "cmexamplebatch123",
  "status": "queued",
  "featureId": "0x808fbb38fa3f36f9:0xf5692002b984147",
  "startAt": "2026-08-01T00:00:00Z",
  "endAt": "2026-08-20T00:00:00Z",
  "endExclusive": true,
  "hl": "en",
  "gl": "us",
  "format": "ndjson",
  "contentType": "application/x-ndjson",
  "contentEncoding": "gzip",
  "progress": {
    "completedShards": 0,
    "shardCount": 10,
    "pagesFetched": 0,
    "reviewsMatched": 0,
    "reviewsExported": 0
  },
  "requestsCharged": 0,
  "truncatedByQuota": false,
  "attempts": 0,
  "maxAttempts": 3,
  "nextAttemptAt": "2026-08-20T14:00:00Z",
  "fileSizeBytes": 0,
  "fileName": "google-reviews-cmexamplebatch123.ndjson.gz",
  "createdAt": "2026-08-20T14:00:00Z",
  "links": {
    "self": "/api/v1/reviews/batches/cmexamplebatch123"
  }
}

Lifecycle fields that do not apply yet are omitted from the JSON rather than returned as null.

List, poll, and cancel jobs

List responses have the shape {"jobs": [ReviewBatchJob, ...]}. The optional limit query parameter defaults to 20 and is clamped to 1–100. Job IDs are owner-scoped: another account cannot inspect, cancel, or download your export.

# List recent jobs
curl "https://api.serpsearch.com/api/v1/reviews/batches?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Poll one job
curl "https://api.serpsearch.com/api/v1/reviews/batches/cmexamplebatch123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Request cancellation
curl -X DELETE "https://api.serpsearch.com/api/v1/reviews/batches/cmexamplebatch123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancellation returns 202 Accepted. Queued jobs are cancelled immediately; running jobs stop cooperatively and may report progress before reaching cancelled.

Quota, charging, and partial delivery

Each Google review page requested by the workers counts as one monthly API request, regardless of how many reviews that page contains. While a job is running, those requests are reserved: they reduce your available quota but are not added to consumed usage. The final page total is charged once, in the same database transaction that marks the uploaded artifact available for download.

Cancelled jobs, terminally failed jobs, and failed retry attempts do not consume their reservations. Job creation, listing, polling, cancellation, and download-link requests are still subject to the requests-per-second limit, but do not deduct monthly request quota.

Download a completed export

Once the job is completed, request its download resource. The API returns a signed URL valid for 15 minutes. The private export itself remains available for seven days after completion, so you can request another signed URL until expiresAt.

curl "https://api.serpsearch.com/api/v1/reviews/batches/cmexamplebatch123/download" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "url": "https://review-export-bucket.s3.amazonaws.com/...",
  "expiresAt": "2026-08-20T14:20:00Z",
  "contentType": "application/x-ndjson",
  "contentEncoding": "gzip",
  "fileName": "google-reviews-cmexamplebatch123.ndjson.gz"
}

NDJSON review schema

After gzip decompression, each line is one JSON review entry using the same review schema as GET https://api.serpsearch.com/api/v1/reviews. Optional fields, including an owner response, are omitted when Google does not provide them.

{"review":{"id":"abc123","rating":5,"text":"Amazing place!","lang":"en","created_at":1786032000,"link":"https://..."},"user":{"id":"1234567890","name":"John D.","image_url":"https://...","review_count":42,"profile_url":"https://..."},"response":{"text":"Thank you!","lang":"en","created_at":1786118400}}

Batch error responses

Review batch endpoints return errors as a JSON object containing a human-readable error string:

{
  "error": "review export is not ready for download"
}

{
  "mcpServers": {
    "serpsearch": {
      "type": "http",
      "url": "https://mcp.serpsearch.com/mcp"
    }
  }
}

Error Codes

All errors follow the same envelope shape:

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

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.

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: