2026-09-17, Rank Tracking · SERP API · Google

Build a Google rank tracker: positions, depth, storage

A rank tracker records, for each keyword, market and day, where a domain’s pages appear in Google’s organic results. On this API that means one Google Search request per observation, reading organicResults[].position for the first result on your domain, and storing it with the targeting that produced it. The work is in the details: which position you mean, how deep you look, where the search is run from, and how you decide that a returned URL is yours.

The rank tracking API page covers the job end to end; this post is the tracker itself. Batch submission, the webhook receiver and reconciliation are covered in building a rank-tracking pipeline with async batches and not repeated here.

Definitions

• Organic position: the 1-indexed rank of a result among Google’s organic listings, as returned in organicResults[].position.
• Page: the results page an organic result appeared on, 1-indexed, as returned in organicResults[].page.
• Absolute position: a rank that also counts non-organic blocks above a result (ads, AI Overview, local pack, People Also Ask). Not returned by this API; see below.
• Observation: one keyword, in one market, at one time. The unit of storage and of billing.
• Best rank: the lowest position of any result on your domain in one observation. Most trackers report this one number per keyword.

Which position you are tracking

Organic position, as returned

A Google Search response lists organic listings in result.organicResults[]. Each item has position (1-indexed), title, link, displayedLink, snippet, date, page and, when Google shows them, sitelinks.inline[]. When you request several pages, organic results from all pages are listed in one array and position keeps counting across them: the first result on page 2 continues from the last position on page 1 and carries page: 2. Sitelinks sit inside their parent result and do not take positions of their own.

It is the number to compare from day to day.

Why absolute rank cannot be derived exactly

Everything else on the page comes back as its own array with its own numbering:

The response does not say where the local pack sat relative to organic result 2, or whether People Also Ask came after result 3 or result 5, and it carries no pixel offsets. So a “pixel rank” or an “absolute rank including features” cannot be computed exactly from the structured fields. You can approximate: count top ads (blockPosition: "top") and, if aioverview is present, one block for it, and add them to the organic position. Label that number as an estimate in reports.

Google’s own Search Console uses a third definition. Its help page says position is calculated “from top to bottom on the primary side of the page, then top to bottom on the secondary side”, that each element such as a carousel occupies a single position, and that an AI Overview “occupies a single position in search results, and all links in the AI Overview are assigned that same position” (Search Console: impressions, position and clicks, checked 2026-09-17). The same page notes that a position is recorded only when a result gets an impression, so a result on page 3 gets no Search Console position for a search where the user only viewed page 1. Expect Search Console average position and a tracker’s organic position to differ, and do not reconcile them line by line.

Track SERP features next to organic rank rather than folding them into it. SERP feature change tracking shows how to snapshot them from the same response.

Depth: the pages field

The standard request takes pages from 1 to 10 (default 1). There is no num or start field in that shape. The API treats a page as 10 results when it converts a URL’s num to pages, so pages: 10 is the equivalent of looking about 100 results deep; the exact count per page is whatever Google rendered.

Rank trackers used to fetch 100 results in one Google request with the &num=100 URL parameter. A Botify write-up dated 2025-10-15 reports that Google removed it between September 8 and 10, 2025, “with no warning and no supporting documentation” (Botify, checked 2026-09-17). The API handles depth as whole pages instead: if you send a complete Google URL in the alternative url shape, its num is read as result depth, rounded up to whole pages of 10 and capped at 10 pages. You cannot combine url with pages.

How deep to go is a cost decision:

A tiered schedule keeps cost proportional to value: every keyword weekly at pages: 3, the keywords currently ranking in the top 10 daily at pages: 1, and a monthly pages: 10 sweep to catch pages entering from far down. You are charged for pages returned, so a query with few results costs less than its reservation.

Where the search runs from

Rankings depend on where and how the search is made. The targeting is part of the observation’s identity, and changing it starts a new series.

• Country: country (ISO 3166-1 alpha-2) or its alternative gl, same codes, either case. Sending both with different values is a 400. Google Search accepts 213 countries, listed by GET /v1/countries?model=google.
• Language, city and device: hl, location/uule and device (desktop, mobile, ios, android). Without hl, the interface language is the country’s own.

For map-pack positions see local rank tracking; for the general use case see rank tracking.

One observation, three ways

A synchronous call is the simplest way to see the shape. Use it for spot checks and on-demand lookups, and use async tasks for scheduled runs.

curl -X POST https://api.answerline.dev/v1/monitor/google \
  -H "Authorization: Bearer $ANSWERLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "project management software",
    "country": "US",
    "pages": 3
  }'

import os
import requests

API = "https://api.answerline.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['ANSWERLINE_API_KEY']}"}

res = requests.post(
    f"{API}/v1/monitor/google",
    json={"query": "project management software", "country": "US", "pages": 3},
    headers=HEADERS,
    timeout=(10, 330),
)
res.raise_for_status()
for r in res.json()["result"]["organicResults"]:
    print(r["position"], r["page"], r["link"])

const res = await fetch("https://api.answerline.dev/v1/monitor/google", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ANSWERLINE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "project management software",
    country: "US",
    pages: 3,
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
const { result } = await res.json();
for (const r of result.organicResults) console.log(r.position, r.page, r.link);

This costs $0.00103 + $0.00071 × 2 for the extra pages = $0.00245.

Matching URLs: where trackers go wrong

Deciding whether a returned link is “yours” causes more wrong ranks than anything Google does. Decide on two levels.

Domain match answers “does the site rank”. Compare hostnames, not strings:

1. Parse link and take the hostname; lowercase it.
2. Strip a leading www..
3. Accept the domain itself and its subdomains (blog.example.com counts for example.com), unless you track subdomains as separate properties.
4. Never match with in on the raw URL: example.com is a substring of notexample.com and of example.com.evil.test.

Page match answers “does this specific URL rank”. Normalize both sides before comparing: drop the fragment, drop tracking parameters such as utm_*, treat a trailing slash as insignificant, and compare scheme-less. Keep other query parameters unless you know they are cosmetic.

Other pitfalls:

• Use link, not displayedLink. displayedLink is the formatted URL Google shows, which may be a breadcrumb-style path rather than a URL.
• Redirects. When Google served a result as a /goto redirect, link holds the resolved destination and redirectLink holds Google’s redirect. Match on link.
• Cannibalization. A different page from your site may rank instead of the target page. Store every result on your domain, including those below the first, so you can see the swap.
• Duplicates across pages. Record best rank per domain per observation, and keep the full list for analysis.
• Sitelinks are not ranks. A URL that appears only in sitelinks.inline[] of your homepage result has not ranked on its own.

from urllib.parse import urlsplit, parse_qsl, urlencode

def host(url: str) -> str:
    return (urlsplit(url or "").hostname or "").lower().removeprefix("www.")

def on_domain(url: str, domain: str) -> bool:
    h = host(url)
    return h == domain or h.endswith("." + domain)

def page_key(url: str) -> str:
    p = urlsplit(url)
    query = urlencode([(k, v) for k, v in parse_qsl(p.query) if not k.startswith("utm_")])
    path = p.path.rstrip("/") or "/"
    return f"{host(url)}{path}" + (f"?{query}" if query else "")

def ranks(result: dict, domain: str) -> list[dict]:
    return [
        {"position": r["position"], "page": r["page"], "url": r["link"], "page_key": page_key(r["link"])}
        for r in result.get("organicResults") or []
        if on_domain(r.get("link"), domain)
    ]

Storage schema

Store one row per observation and one row per ranking URL on the domains you track. Keep the raw response in object storage keyed by task id, so new metrics can be computed later without paying for the pages again.

create table keywords (
  keyword_id bigserial primary key,
  query text not null,
  unique (query)
);

create table observations (
  observation_id bigserial primary key,
  keyword_id bigint not null references keywords,
  country text not null,
  pages smallint not null,
  day date not null,
  task_id text not null unique,
  status text not null,               -- COMPLETED or FAILED
  organic_count smallint,             -- results returned, to spot short pages
  has_aioverview boolean,
  top_ads smallint,
  unique (keyword_id, country, day)
);

create table rankings (
  observation_id bigint not null references observations,
  domain text not null,
  position smallint not null,
  page smallint not null,
  url text not null,
  page_key text not null,
  primary key (observation_id, domain, position)
);

-- best rank per domain per day
create view best_rank as
select o.keyword_id, o.country, o.day, r.domain, min(r.position) as position
from observations o
join rankings r using (observation_id)
where o.status = 'COMPLETED'
group by 1, 2, 3, 4;

Design notes:

• pages is stored because “not in the top 30” and “not in the top 100” are different facts. A missing ranking row means “not found within the depth requested”, never “position 0”.
• A FAILED observation keeps its row with no rankings. Excluding it from best_rank keeps a failure from looking like a drop out of the results.
• Tracking competitors costs nothing extra: insert rankings for every domain you care about from the same response.
• The unique key on the observation mirrors the idempotency key you send, so duplicate webhook deliveries cannot create a second row.

Scheduling with async batches and webhooks

For anything beyond a few dozen keywords, submit GOOGLE tasks to POST /v1/async/task/batch (1 to 500 tasks per request) with an idempotencyKey derived from the observation and a webhook: {"url": ...}. Each finished task is POSTed to the webhook, signed with Webhook-Signature; GET /v1/async/task/{taskId} returns the same body for reconciliation.

type Obs = { keywordId: string; query: string; country: string; pages: number };

export async function submitDay(obs: Obs[], day: string, webhookUrl: string) {
  const tasks = obs.map((o) => ({
    taskType: "GOOGLE",
    payload: {
      query: o.query,
      country: o.country,
      pages: o.pages,
    },
    idempotencyKey: `rank:${o.keywordId}:${o.country}:${day}`,
    webhook: { url: webhookUrl },
  }));
  for (let i = 0; i < tasks.length; i += 500) {
    const res = await fetch("https://api.answerline.dev/v1/async/task/batch", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.ANSWERLINE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(tasks.slice(i, i + 500)),
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
    const { results } = await res.json();
    for (const r of results) {
      if (!r.success && r.error.code !== "RESOURCE_ALREADY_EXISTS") console.warn(r.index, r.error);
    }
  }
}

Keep keys short; hash long values if needed. The receiver, signature check, reconciliation sweep and failure table are in the async batch pipeline, and the delivery rules are on webhooks and async tasks. Run the submission at the same time each day, so time of day is held constant across the series.

Cost

From the current Starter-tier prices: a Google Search task costs $0.00103, each page beyond the first adds $0.00071, and include.aioverview adds $0.00071 once when Google shows an overview; include.paaAioverview is free.

These are upper bounds: failed tasks are not charged, and page charges follow the pages returned. Validate matching and storage on a small keyword set before sizing a budget against the tiers on the pricing page; the 100 free requests new accounts get are enough for that first test. For sizing method, see estimating your monitoring bill.

Reporting ranks without misleading anyone

• Report best rank together with the URL that holds it. A number without the URL hides cannibalization.
• Bucket before trending: the share of keywords in positions 1-3, 4-10, 11-30 and not found is steadier than an average.
• Do not average “not found”. Substituting 101 for missing ranks invents data. Report coverage separately.
• Compare like with like: same market and depth, or it is not a trend.
• Alert on moves that hold for two consecutive runs rather than on a single observation, as in SERP feature change tracking.

Other data in the same response

The same response carries data that sits next to rank: AI Overview sources (what AI Overviews cite), People Also Ask questions (PAA for content strategy), and related searches (people also search for). For an overview of every block on the page, read what is a SERP. For the AI-assistant equivalent of rank, citation rank, see the async batch pipeline and GEO vs SEO metrics.

Field shapes for every block are on the Google Search engine page.

Keep reading