Rank Tracker API — Build Trackers, Reports & Dashboards on Live Position Data

# 1. Where does this keyword rank on Google in the US, top 50?
curl "https://apiserpent.com/api/search/quick?q=best+running+shoes&engine=google&country=us&num=50" \
  -H "X-API-Key: YOUR_API_KEY"

# 2. The same keyword, three columns only — position, title, url
curl "https://apiserpent.com/api/search/quick?q=best+running+shoes&engine=google&num=20&format=simple" \
  -H "X-API-Key: YOUR_API_KEY"

# 3. The same keyword in a second market, in its own language
curl "https://apiserpent.com/api/search/quick?q=laufschuhe+test&engine=google&country=de&language=de&num=20" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "query": "best running shoes",
  "type": "web",
  "engine": "google",
  "country": "us",
  "pagesScraped": 5,
  "results": [
    { "position": 1, "title": "…", "url": "https://example.com/a" },
    { "position": 2, "title": "…", "url": "https://example.com/b" },
    { "position": 3, "title": "…", "url": "https://example.com/c" }
  ],
  "meta": {
    "total": 50,             // rows you actually got — store this
    "requestedNum": 50,
    "elapsed": "2841ms",
    "timestamp": "2026-09-07T09:12:04.000Z"
  }
}

// Had this call come back short, it would also carry a top-level block:
//   "delivery": { "requested": 100, "returned": 63, "note": "…" }
// A full answer has no `delivery` key at all.

import os, sqlite3, datetime, requests

API    = "https://apiserpent.com/api/search/quick"
KEY    = os.environ["SERPENT_API_KEY"]
DOMAIN = "yoursite.com"
DEPTH  = 50   # num=50 and below delivers in full

db = sqlite3.connect("ranks.db")
db.execute("""CREATE TABLE IF NOT EXISTS rank_log (
  day TEXT, keyword TEXT, engine TEXT, country TEXT,
  position INTEGER,   -- NULL = we looked and did not find it
  scanned  INTEGER,   -- how many rows we actually looked at
  short    INTEGER,   -- 1 = we got a smaller window than we asked for
  url      TEXT,
  PRIMARY KEY (day, keyword, engine, country))""")

def check(keyword, engine="google", country="us"):
    r = requests.get(API, headers={"X-API-Key": KEY}, params={
        "q": keyword, "engine": engine, "country": country,
        "num": DEPTH, "format": "simple"}, timeout=60)
    r.raise_for_status()
    body = r.json()

    rows    = body["results"]              # format=simple: a flat list
    scanned = body["meta"]["total"]
    # `delivery` is present ONLY when we named a depth and came up short.
    short   = bool(body.get("delivery"))

    hit = next((x for x in rows if DOMAIN in x["url"]), None)
    return {
        "position": hit["position"] if hit else None,
        "url":      hit["url"]      if hit else None,
        "scanned":  scanned,
        "short":    short,
    }

day = datetime.date.today().isoformat()
for line in open("keywords.txt"):
    kw = line.strip()
    if not kw: continue
    row = check(kw)
    # A missing domain in a SHORT window is not a drop — flag it, do not plot it.
    db.execute("INSERT OR REPLACE INTO rank_log VALUES (?,?,?,?,?,?,?,?)",
               (day, kw, "google", "us",
                row["position"], row["scanned"], int(row["short"]), row["url"]))
    db.commit()

const engines = ["google", "bing", "yahoo", "ddg", "brave"];

for (const engine of engines) {
  const url = `https://apiserpent.com/api/search/quick`
    + `?q=serp+api&engine=${engine}&country=us&num=20&format=simple`;
  const res  = await fetch(url, { headers: { "X-API-Key": process.env.SERPENT_API_KEY } });
  const body = await res.json();

  const hit = body.results.find(r => r.url.includes("yoursite.com"));
  // Say WHICH kind of "no" it was — the two mean different things.
  const verdict = hit          ? `#${hit.position}`
                : body.delivery ? `not in ${body.meta.total} rows (asked for 20)`
                :                 `not in top ${body.meta.total}`;
  console.log(engine.padEnd(7), verdict);
}