Google SERP (v2) Reference

The v2 SERP API provides advanced Google search result crawling with configurable depth for multi-page result collection.

Create Google SERP Task

POST /api/v2/serp/crawl

Create a new Google SERP crawl task. The task is processed asynchronously and results can be retrieved via polling or webhook.

Request Parameters

Parameter	Type	Required	Description
`keyword`	string	Required	The search query to crawl
`location_name`	string	Required	Geographic location (e.g., "United States", "London,United Kingdom")
`iso_code`	string	Required	Country ISO code (e.g., "US", "GB")
`depth`	integer	Optional	Number of results to fetch (1-100). Default: 10
`device`	string	Optional	`desktop` or `mobile`. Default: desktop
`language_code`	string	Optional	Language code (e.g., "en", "es")
`domain`	string	Optional	Your domain to track in results
`business_name`	string	Optional	Business name to track in local pack results
`competitors`	array	Optional	List of competitor domains to track. Each object: `{"competitor": "domain.com", "type": "domain"}`
`postback_url`	string	Optional	Webhook URL for result delivery
`frequency`	integer	Optional	Cache duration in hours. Reuse recent results within this window. Default: 24
`se_id`	integer	Optional	Search engine configuration ID from Locations API
`engine_domain`	string	Optional	Google domain to use (e.g., "google.co.uk"). Default: "google.com"
`post_id`	string	Optional	Custom identifier to associate with this task
`keyword_id`	integer	Optional	Custom keyword ID for tracking purposes

Request Example

curl -X POST "https://engine.v2.serpwatch.io/api/v2/serp/crawl" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "best project management software",
    "location_name": "United States",
    "iso_code": "US",
    "depth": 50,
    "device": "desktop",
    "language_code": "en"
  }'

import requests

response = requests.post(
    "https://engine.v2.serpwatch.io/api/v2/serp/crawl",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "keyword": "best project management software",
        "location_name": "United States",
        "iso_code": "US",
        "depth": 50,
        "device": "desktop",
        "language_code": "en"
    }
)

task = response.json()
print(f"Task ID: {task['id']}")

const response = await fetch(
  "https://engine.v2.serpwatch.io/api/v2/serp/crawl",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      keyword: "best project management software",
      location_name: "United States",
      iso_code: "US",
      depth: 50,
      device: "desktop",
      language_code: "en"
    })
  }
);

const task = await response.json();
console.log(`Task ID: ${task.id}`);

Response

{
  "id": 1166085028196491264,
  "user_id": 1134894642391789569,
  "status": "awaiting",
  "keyword": "best project management software",
  "location_name": "United States",
  "iso_code": "US",
  "device": "desktop",
  "depth": 50,
  "language_code": "en",
  "frequency": 24,
  "postback_url": null,
  "result": null,
  "created_on": "2026-01-29",
  "created_at": 1769712336,
  "ttl": 1769798736
}

Track Domain Ranking

When you include a domain parameter in your request, the API returns a different response structure optimized for rank tracking. Instead of raw SERP data, you get structured ranking information for your domain and all competitors found in the results.

Request with Domain Tracking

curl -X POST "https://engine.v2.serpwatch.io/api/v2/serp/crawl" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "project management software",
    "location_name": "United States",
    "iso_code": "US",
    "depth": 10,
    "device": "desktop",
    "language_code": "en",
    "domain": "monday.com"
  }'

import requests

response = requests.post(
    "https://engine.v2.serpwatch.io/api/v2/serp/crawl",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "keyword": "project management software",
        "location_name": "United States",
        "iso_code": "US",
        "depth": 10,
        "device": "desktop",
        "language_code": "en",
        "domain": "monday.com"
    }
)

task = response.json()
print(f"Task ID: {task['id']}")

const response = await fetch(
  "https://engine.v2.serpwatch.io/api/v2/serp/crawl",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      keyword: "project management software",
      location_name: "United States",
      iso_code: "US",
      depth: 10,
      device: "desktop",
      language_code: "en",
      domain: "monday.com"
    })
  }
);

const task = await response.json();
console.log(`Task ID: ${task.id}`);

Response with Domain Tracking (Completed)

When the task completes, the result object contains ranking data keyed by domain name:

{
  "id": 1166212871702687744,
  "status": "success",
  "keyword": "project management software",
  "domain": "monday.com",
  "location_name": "United States",
  "iso_code": "US",
  "device": "desktop",
  "depth": 10,
  "result": {
    "monday.com": {
      "type": "owner",
      "keyword_id": null,
      "results": {
        "organic": {
          "position": "1000",
          "type": "organic",
          "snippet": "-",
          "title": "-",
          "url": "-"
        }
      }
    },
    "project-management.com": {
      "type": "competitor_free",
      "keyword_id": null,
      "results": {
        "organic": {
          "position": "1",
          "type": "organic",
          "snippet": "Discover the best free project management software...",
          "title": "Best Project Management Software Reviewed by Experts",
          "url": "https://project-management.com/top-10-project-management-software/"
        }
      }
    },
    "thedigitalprojectmanager.com": {
      "type": "competitor_free",
      "keyword_id": null,
      "results": {
        "organic": {
          "position": "2",
          "type": "organic",
          "snippet": "The best project management software helps you plan projects...",
          "title": "40 Best Project Management Software Picked For 2026",
          "url": "https://thedigitalprojectmanager.com/tools/best-project-management-software/"
        }
      }
    }
  },
  "top_10": [
    "project-management.com",
    "thedigitalprojectmanager.com",
    "reddit.com",
    "paymoapp.com",
    "microsoft.com",
    "zapier.com",
    "wikipedia.org"
  ]
}

Domain Tracking Response Fields

Field	Type	Description
`result.{domain}.type`	string	`owner` for your tracked domain, `competitor_free` for other domains found
`result.{domain}.results.organic.position`	string	Ranking position. `"1000"` means not found in results
`result.{domain}.results.organic.title`	string	Page title. `"-"` if not found
`result.{domain}.results.organic.url`	string	Full URL of the ranking page. `"-"` if not found
`result.{domain}.results.organic.snippet`	string	Meta description snippet. `"-"` if not found
`top_10`	array	List of domains ranking in top positions

Position 1000

When your tracked domain is not found in the search results, it appears with position: "1000" and placeholder values ("-") for title, URL, and snippet. This indicates the domain is not ranking within the requested depth.

Create Batch Google SERP Tasks

POST /api/v2/serp/crawl/google/batch

Create multiple Google SERP crawl tasks in a single request. Returns an array of task objects.

Request Body

Array of task objects. Each object accepts the same parameters as the single create endpoint.

Request Example

curl -X POST "https://engine.v2.serpwatch.io/api/v2/serp/crawl/google/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "keyword": "project management software",
      "location_name": "United States",
      "iso_code": "US",
      "depth": 20,
      "device": "desktop"
    },
    {
      "keyword": "task management tools",
      "location_name": "United States",
      "iso_code": "US",
      "depth": 20,
      "device": "desktop"
    },
    {
      "keyword": "team collaboration apps",
      "location_name": "United Kingdom",
      "iso_code": "GB",
      "depth": 20,
      "device": "mobile"
    }
  ]'

import requests

keywords = [
    {"keyword": "project management software", "device": "desktop"},
    {"keyword": "task management tools", "device": "desktop"},
    {"keyword": "team collaboration apps", "device": "mobile"}
]

batch = [
    {**kw, "depth": 20, "location_name": "United States", "iso_code": "US"}
    for kw in keywords
]

response = requests.post(
    "https://engine.v2.serpwatch.io/api/v2/serp/crawl/google/batch",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json=batch
)

tasks = response.json()
print(f"Created {len(tasks)} tasks")

Response

[
  {
    "id": 1166085028196491001,
    "status": "awaiting",
    "keyword": "project management software",
    "location_name": "United States",
    "iso_code": "US",
    "device": "desktop",
    "depth": 20
  },
  {
    "id": 1166085028196491002,
    "status": "awaiting",
    "keyword": "task management tools",
    "location_name": "United States",
    "iso_code": "US",
    "device": "desktop",
    "depth": 20
  },
  {
    "id": 1166085028196491003,
    "status": "awaiting",
    "keyword": "team collaboration apps",
    "location_name": "United Kingdom",
    "iso_code": "GB",
    "device": "mobile",
    "depth": 20
  }
]

Get Task Results

GET /api/v2/serp/crawl/{task_id}

Retrieve the status and results of a SERP crawl task.

Path Parameters

Parameter	Type	Description
`task_id`	integer	The task ID returned when creating the task

Request Example

curl -X GET "https://engine.v2.serpwatch.io/api/v2/serp/crawl/1166085028196491264" \
  -H "Authorization: Bearer YOUR_API_KEY"

task_id = 1166085028196491264

response = requests.get(
    f"https://engine.v2.serpwatch.io/api/v2/serp/crawl/{task_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

result = response.json()
print(f"Status: {result['status']}")

Response (Completed Task)

{
  "id": 1166085028196491264,
  "user_id": 1134894642391789569,
  "status": "success",
  "keyword": "best project management software",
  "location_name": "United States",
  "iso_code": "US",
  "device": "desktop",
  "depth": 50,
  "language_code": "en",
  "frequency": 24,
  "created_on": "2026-01-29",
  "created_at": 1769712336,
  "result": {
    "left": [
      {
        "type": "organic",
        "position": "1",
        "url": "https://example.com/pm-software-comparison",
        "breadcrumb": "https://example.com › pm-software-comparison",
        "title": "15 Best Project Management Software of 2026",
        "snippet": "Compare the top project management tools for teams of all sizes..."
      },
      {
        "type": "organic",
        "position": "2",
        "url": "https://reviews.com/project-management",
        "breadcrumb": "https://reviews.com › project-management",
        "title": "Top 10 Project Management Tools | Expert Reviews",
        "snippet": "In-depth reviews of the most popular PM software solutions..."
      },
      {
        "type": "related_search",
        "position": "9",
        "title": "",
        "items": [
          "project management software free",
          "project management tools",
          "enterprise project management software"
        ]
      }
    ],
    "right": []
  },
  "top_10": ["example.com", "reviews.com", "monday.com", "asana.com"],
  "pages": [
    {
      "page": 1,
      "url": "https://www.google.com/search?q=...",
      "status": "success",
      "retry_count": 0,
      "html": "production/2026-01-29/google-multipage/1166085028196491264-1.html"
    }
  ]
}

Response Schema

Task Object

Field	Type	Description
`id`	integer	Unique task identifier
`user_id`	integer	User ID who created the task
`status`	string	Task status: `awaiting`, `crawling`, `parsing`, `success`, `error`
`keyword`	string	The search query
`location_name`	string	Geographic location
`iso_code`	string	Country ISO code
`result`	object	SERP results (present when status is success)
`top_10`	array	List of top 10 ranking domains
`pages`	array	SERP page data for multi-page results
`created_at`	integer	Unix timestamp when task was created
`ttl`	integer	Unix timestamp when task data expires

Result Object

Field	Type	Description
`left`	array	Main SERP results (organic, ads, related searches, etc.)
`right`	array	Right sidebar results (knowledge panels, etc.)

Result Item Object (in left/right arrays)

Field	Type	Description
`type`	string	Result type: `organic`, `ad`, `related_search`, `featured_snippet`, etc.
`position`	string	Ranking position (1-based)
`title`	string	Page title
`url`	string	Full URL
`breadcrumb`	string	Breadcrumb URL displayed in SERP
`snippet`	string	Meta description or snippet text
`items`	array	For `related_search` type: list of related search terms

Error Responses

Status Code	Description
`400`	Bad Request - Invalid JSON or empty batch
`401`	Unauthorized - Invalid or missing API key
`404`	Not Found - Task ID does not exist
`422`	Validation Error - Missing required fields or invalid values
`429`	Rate Limited - Too many requests

See Error Codes for detailed error handling guidance.