Keyword ranking api

Pick the right provider for your use case

Three real options. **DataForSEO** is the most flexible and cheapest per query - pay-as-you-go from $0.0006-0.005 per SERP. **Ahrefs API** is the deepest dataset but only available on Enterprise plans starting ~$1,500/mo. **SEMrush API** is comparable to Ahrefs, also Enterprise-tier. **Serpstat** offers an API on standard plans, mid-tier price/quality. For most teams building rank tracking from scratch, DataForSEO is the right starting point.

Authenticate and test a single keyword query

Every provider authenticates via API key in the header. Start with one keyword + one location to validate auth + parsing before scaling. The DataForSEO Live SERP endpoint returns a full JSON SERP including organic, paid, and SERP features - test that you can parse the position you actually want.

// DataForSEO Live SERP - Node example
const res = await fetch('https://api.dataforseo.com/v3/serp/google/organic/live/advanced', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + Buffer.from(`${LOGIN}:${PASSWORD}`).toString('base64'),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([{
    keyword: 'keyword ranking api',
    location_code: 2840, // US
    language_code: 'en',
    device: 'desktop',
    depth: 100
  }])
});
const data = await res.json();
const myPosition = data.tasks[0].result[0].items
  .find(i => i.type === 'organic' && i.domain === 'shuttergen.com')?.rank_absolute;

Design your storage schema for time-series rank data

Rank tracking is time-series by nature. Minimum schema: keyword, domain, location, device, position, serp_features (jsonb array), captured_at. Index on (keyword, domain, captured_at desc) for fast 'latest rank' queries. Avoid storing one row per request - store one row per (keyword, domain, day) and dedupe.

-- Postgres schema
create table keyword_rankings (
  id bigserial primary key,
  keyword text not null,
  domain text not null,
  location_code int not null,
  device text not null check (device in ('desktop','mobile')),
  position int, -- null if not in top 100
  url text,
  serp_features jsonb default '[]'::jsonb,
  captured_at timestamptz not null default now()
);
create unique index on keyword_rankings (keyword, domain, location_code, device, date(captured_at));
create index on keyword_rankings (keyword, domain, captured_at desc);

Batch requests to control cost and rate limits

Per-keyword queries get expensive fast. DataForSEO accepts up to 100 tasks per request; batch your keywords accordingly. For weekly tracking of 500 keywords, that's 5 batch requests, costing roughly $1-2.50 per refresh depending on plan. Rate limits: DataForSEO allows 2,000 requests/minute on standard accounts - don't hit it, queue with concurrency 5-10.

Schedule the refresh job

Pick a refresh cadence per keyword tier. Top 20 priority keywords: daily. Next 100: weekly. Long tail: monthly. Use Vercel Cron, Supabase pg_cron, or Cloudflare Workers Cron Triggers - they all support standard cron syntax. Stagger the runs across hours so you don't burn your daily quota in 5 minutes.

// vercel.json - daily 6am UTC for priority keywords
{
  "crons": [
    { "path": "/api/cron/rank-priority", "schedule": "0 6 * * *" },
    { "path": "/api/cron/rank-weekly", "schedule": "0 7 * * 1" }
  ]
}

Parse SERP features alongside positions

Position #1 organic with no SERP features = lots of clicks. Position #1 organic with featured snippet + AI Overview = far fewer clicks. The API returns the full SERP item array - extract featured_snippet, people_also_ask, ai_overview, video, image_pack items into a serp_features jsonb column so you can correlate traffic shifts with SERP changes.

Build alerts on meaningful deltas

Raw rank data is noise without alerting. Define meaningful deltas: position drop of 3+ on a priority keyword, position climb of 5+ (also worth knowing), SERP feature added/removed, competitor entering top 3 on your keyword. Fire to Slack via webhook or email via Resend. Quiet alerts mean missed problems; over-alerting trains the team to ignore them - tune the thresholds.

// Pseudocode alert rule
if (previousPosition && currentPosition - previousPosition >= 3 && isPriorityKeyword) {
  await slack.send(`#seo-alerts`, 
    `${keyword} dropped from #${previousPosition} to #${currentPosition}`);
}

Cross-validate with Search Console

API-fetched rank is a SERP snapshot. Search Console reports your domain's actual impression-weighted position averaged over real queries. They diverge. Use the API for breadth (competitor positions, SERP features, daily volatility) and Search Console for ground truth on your own domain's performance. Pull Search Console daily via its API too and store alongside.