DEV Community

Mastel
Mastel

Posted on Edited on Originally published at serpbase.dev

Check your Google positions every day with Python and a SERP position API

One of the first rank trackers I built stored a single number per keyword. It worked until someone asked why a #1 ranking lost clicks. The page was #1 in the organic list, but it sat below an AI Overview and a People Also Ask block. The tracker was not broken. It was measuring the wrong number.

Google's results page is not a list anymore. A page can be first in the organic list and fourth on the page. If you only store the organic rank, you cannot explain a click drop that is not a ranking drop.

Store two numbers, not one

Each item in SerpBase's organic array carries both:

  • rank — the order within the organic list on that page. This is the classic "we rank #4" number.
  • position — where the result sits on the whole page, counting each module (AI Overview, People Also Ask, local pack, videos) as one block.

A page can be rank: 1 and position: 4. That gap is the story you want in the dashboard. Store both, along with the ranking URL, the country, the language, and the date.

The script

You need Python 3.8+ and one dependency:

pip install requests
Enter fullscreen mode Exit fullscreen mode

Set the key as an environment variable. Do not put it in the file.

export SERPBASE_API_KEY="your_key"
Enter fullscreen mode Exit fullscreen mode
import csv
import os
import time
from datetime import date
from urllib.parse import urlparse

import requests

API = "https://api.serpbase.dev/google/search"
KEY = os.environ["SERPBASE_API_KEY"]


def check(keyword: str, domain: str, gl: str = "us", hl: str = "en") -> dict:
    resp = requests.post(
        API,
        headers={"X-API-Key": KEY, "Content-Type": "application/json"},
        json={"q": keyword, "gl": gl, "hl": hl, "page": 1},
        timeout=20,
    )
    resp.raise_for_status()
    data = resp.json()

    # HTTP 200 is not the success signal. status == 0 is.
    if data.get("status") != 0:
        return {"rank": None, "position": None, "url": "", "error": data.get("status")}

    for item in data.get("organic", []):
        host = urlparse(item.get("link", "")).netloc
        if host == domain or host.endswith("." + domain):
            return {
                "rank": item.get("rank"),
                "position": item.get("position"),
                "url": item.get("link", ""),
                "error": None,
            }

    return {"rank": None, "position": None, "url": "", "error": None}


def run(keywords: list[str], domain: str) -> list[dict]:
    rows = []
    for kw in keywords:
        result = check(kw, domain)
        rows.append(
            {
                "date": date.today().isoformat(),
                "keyword": kw,
                "rank": result["rank"],
                "position": result["position"],
                "url": result["url"],
                "error": result["error"],
            }
        )
        print(f"{kw}: rank={result['rank']} position={result['position']}")
        time.sleep(1)  # keep the run gentle
    return rows


if __name__ == "__main__":
    keywords = [
        "serp api",
        "rank tracking api",
        "google search api",
    ]
    rows = run(keywords, "serpbase.dev")

    with open("positions.csv", "a", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(
            f,
            fieldnames=["date", "keyword", "rank", "position", "url", "error"],
        )
        if f.tell() == 0:
            writer.writeheader()
        writer.writerows(rows)

    print(f"wrote {len(rows)} rows to positions.csv")
Enter fullscreen mode Exit fullscreen mode

Run it once, then schedule it:

crontab -e
0 8 * * * /usr/bin/python3 /path/to/rank_tracker.py >> /var/log/rank_tracker.log 2>&1
Enter fullscreen mode Exit fullscreen mode

Three details that will save you later

Check status, not the HTTP code. A failed search returns a non-zero status in the body. If you treat that as "not ranking", you will write a fake drop into the database.

Keep the URL. A keyword can stay at rank: 3 while the ranking URL changes from a blog post to a product page. The position did not move; the page did.

Use gl and hl explicitly. Rankings are not global. Store the country and language with every row so a future comparison does not mix markets.

What it costs

One Google web search is 1 credit. New accounts get 500 free credits without a card. At the Pro Monthly tier the rate is $0.25 per 1,000 searches; smaller packs cost more per search. A daily run of 100 keywords is about 3,000 requests a month, which is under $1 at that rate.

If you need positions 11–20, set page: 2 and add the number of organic results you already counted to rank. Keep the raw position as returned.

The longer version of this method, including localization and competitor tracking, is here: Rank tracking API for SEO tools: build a SERP tracker for Google positions.

Start with 20 keywords in one market. Store both numbers for two weeks before adding a second market. The first time rank stays the same and position moves, you will see why the single number was not enough.

Top comments (0)