v2.0
Swagger UI Get Started

SERP Endpoints (v1) Reference

The v1 SERP API provides search result crawling for Google, Bing, and Yahoo with both live (synchronous) and task-based (asynchronous) options.

v1 vs v2

For Google searches, we recommend using the v2 endpoints which offer improved depth control and multi-page result collection. The v1 endpoints remain available for Bing, Yahoo, and backwards compatibility.

Endpoints Overview

Endpoint Method Description
/api/v1/serp/google/crawl POST Create Google SERP task (async)
/api/v1/serp/google/crawl/live POST Get Google SERP results immediately (sync)
/api/v1/serp/bing/crawl POST Create Bing SERP task (async)
/api/v1/serp/bing/crawl/live POST Get Bing SERP results immediately (sync)
/api/v1/serp/yahoo/crawl POST Create Yahoo SERP task (async)
/api/v1/serp/yahoo/crawl/live POST Get Yahoo SERP results immediately (sync)
/api/v1/serp/crawl/{task_id} GET Retrieve task results

Google SERP

POST /api/v1/serp/google/crawl

Create a Google SERP crawl task. Returns a task ID for async result retrieval.

Request Parameters

Parameter Type Required Description
keyword string Required The search query
location_name string Required Geographic location (e.g., "United States", "London,United Kingdom")
iso_code string Required Country ISO code (e.g., "US", "GB")
language_code string Optional Language code (e.g., "en", "es")
device string Optional desktop or mobile. Default: desktop
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. Default: 24
se_id integer Optional Search engine configuration ID from Locations API
engine_domain string Optional Search engine domain to use (e.g., "google.co.uk")
post_id string Optional Custom identifier to associate with this task
keyword_id integer Optional Custom keyword ID for tracking purposes

Example Request

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

response = requests.post(
    "https://engine.v2.serpwatch.io/api/v1/serp/google/crawl",
    headers={
        "Authorization": f"Bearer {os.environ['SERPWATCH_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "keyword": "best project management software",
        "location_name": "United States",
        "iso_code": "US",
        "language_code": "en",
        "device": "desktop"
    }
)

task = response.json()
print(f"Task ID: {task['id']}")
const response = await fetch(
  "https://engine.v2.serpwatch.io/api/v1/serp/google/crawl",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SERPWATCH_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      keyword: "best project management software",
      location_name: "United States",
      iso_code: "US",
      language_code: "en",
      device: "desktop"
    })
  }
);

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

Response

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

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/v1/serp/google/crawl" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "project management software",
    "location_name": "United States",
    "iso_code": "US",
    "language_code": "en",
    "device": "desktop",
    "domain": "monday.com"
  }'
import requests

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

task = response.json()
print(f"Task ID: {task['id']}")
const response = await fetch(
  "https://engine.v2.serpwatch.io/api/v1/serp/google/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",
      language_code: "en",
      device: "desktop",
      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",
  "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"
  ]
}

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.

Google SERP Live

POST /api/v1/serp/google/crawl/live

Get Google SERP results synchronously. The response includes the full SERP data immediately.

Performance Note

Live endpoints wait for results before responding. Use async endpoints for batch processing or high-volume requests.

Example Request

curl -X POST "https://engine.v2.serpwatch.io/api/v1/serp/google/crawl/live" \
  -H "Authorization: Bearer $SERPWATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "project management tools",
    "location_name": "United States",
    "iso_code": "US",
    "language_code": "en"
  }'

Bing SERP

POST /api/v1/serp/bing/crawl

Create a Bing SERP crawl task. Same parameters as Google endpoint.

Example Request

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

Yahoo SERP

POST /api/v1/serp/yahoo/crawl

Create a Yahoo SERP crawl task. Same parameters as Google endpoint.

Get Task Results

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

Retrieve the results of a SERP crawl task. Returns the current status and results if completed.

Path Parameters

Parameter Type Description
task_id integer The task ID returned from the create endpoint

Example Request

curl "https://engine.v2.serpwatch.io/api/v1/serp/crawl/1166085309902725120" \
  -H "Authorization: Bearer $SERPWATCH_API_KEY"

Response (Completed)

{
  "id": 1166085309902725120,
  "user_id": 1134894642391789569,
  "status": "success",
  "keyword": "best project management software",
  "location_name": "United States",
  "iso_code": "US",
  "language_code": "en",
  "device": "desktop",
  "frequency": 24,
  "created_on": "2026-01-29",
  "created_at": 1769712403,
  "result": {
    "left": [
      {
        "type": "organic",
        "position": "1",
        "url": "https://example.com/project-management-software",
        "breadcrumb": "https://example.com › project-management-software",
        "title": "Top 10 Project Management Software in 2026",
        "snippet": "Compare the best project management tools..."
      },
      {
        "type": "organic",
        "position": "2",
        "url": "https://reviews.example.com/pm-software",
        "breadcrumb": "https://reviews.example.com › pm-software",
        "title": "Best Project Management Software | Reviews",
        "snippet": "Expert reviews of leading PM tools..."
      }
    ],
    "right": []
  }
}

Response Schema

Result Item Object

Field Type Description
type string Result type: organic, ad, ai_overview, related_search, etc.
position string Ranking position (1-based)
title string Page title as shown in SERP
url string Full URL of the result
breadcrumb string Breadcrumb URL displayed in SERP
snippet string Meta description or snippet

Task Status Values

Status Description
awaiting Task is queued for processing
crawling Task is being crawled
parsing Results are being parsed
success Task completed successfully
error Task failed with an error

Google SERP (v2)

Advanced Google SERP with multi-page depth support.

Rank Tracking

Learn how to track rankings using SERP data.

Task Lifecycle

Understand async task processing in detail.