The Feature-Rich Rank Tracker

Knowledge-base & Docs

Google SERP (v2)

11 views 0 February 5, 2026

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.

Was this helpful?

 
Related Articles