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

Build Google rank tracking on a SERP API: positions, pages, locations and storage

A rank tracker records, for each keyword, market, device 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.

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, on one device, 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. If you need the real layout, request include.html and read the raw page from the URLs returned in result.html[].

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 actually 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. Every targeting field below is part of the observation’s identity, and changing any of them 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. GET /v1/countries?model=google lists supported codes.
• Language: hl sets Google’s interface language (en, de, pt-BR) and overrides the language derived from the country. Set it explicitly for multilingual markets such as Canada, Switzerland or Belgium.
• City or region: location takes a Google canonical name in City,Region,Country form, such as "Austin,Texas,United States", from the Google Ads geotargets list. Alternatively send a pre-encoded uule. The two are mutually exclusive.
• Device: device is desktop (default), mobile, ios or android. ios, android and mobile return the mobile SERP; mobile is an alias for android.

Desktop and mobile are different pages. localResults is returned for desktop searches only, so a mobile series never includes it. For city-level tracking and 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",
    "hl": "en",
    "location": "Austin,Texas,United States",
    "device": "desktop",
    "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", "hl": "en",
          "location": "Austin,Texas,United States", "device": "desktop", "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",
    hl: "en",
    location: "Austin,Texas,United States",
    device: "desktop",
    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);

As a synchronous call this costs 3 + 2 × 2 + 2 = 9 credits; the same payload as an async GOOGLE task costs 7.

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, not just 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,
  hl text not null default '',
  location text not null default '',
  device 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, hl, location, device, 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.location, o.device, 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, 5, 6;

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; location?: string; device: 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,
      device: o.device,
      pages: o.pages,
      ...(o.location ? { location: o.location } : {}),
    },
    idempotencyKey: `rank:${o.keywordId}:${o.country}:${o.location ?? ""}:${o.device}:${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 location names 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 in credits

From the current credit prices: a Google Search task costs 3 credits, each page beyond the first adds 2, and include.aioverview (or include.paaAioverview) adds 2 once. Synchronous calls add 2 more; async tasks do not.

These are upper bounds: failed tasks are not charged, and page charges follow the pages returned. The free tier’s 500 monthly credits cover about 160 single-page async observations, enough to validate matching and storage before sizing a plan on the pricing page. 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 device, location, hl 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