@power-seo/analytics

Merge Google Search Console data with audit results, compute Pearson correlations, analyze trends, detect anomalies, and build dashboard-ready aggregated outputs.

@power-seo/analytics is the data intelligence layer of the @power-seo ecosystem. It answers the question that every SEO practitioner asks but most tools cannot answer well: does improving the SEO audit score of a page actually increase its organic traffic? By merging Google Search Console performance data with audit results — keyed on normalized URLs — and computing the Pearson correlation between audit scores and click counts, you can verify the relationship empirically across your own site.

Beyond correlation, the package provides a full trend analysis pipeline: time-series data flows through analyzeTrend (direction, rate of change, confidence) → buildTrendLines (chart-ready data points) → detectAnomalies (statistically significant spikes and drops). The ranking module groups your queries into position buckets (1–3, 4–10, 11–20, 21–50, 50+) matching how SEO professionals think about ranking tiers, and trackPositionChanges produces a before/after diff across two snapshots. Everything culminates in buildDashboardData, which aggregates all of the above into a single structured object ready to be consumed by any charting library or reporting UI.

Zero runtime dependencies — pure TypeScript computation; no external API calls.

Why @power-seo/analytics?

| | Without | With | | ----------------------- | --------------------- | --------------------------------------------------------- | | GSC + audit correlation | ❌ Two separate tools | ✅ Merged by URL with Pearson correlation | | Trend analysis | ❌ Manual spreadsheet | ✅ Direction, rate, confidence in one call | | Anomaly detection | ❌ Manual review | ✅ Statistical spike/drop flagging | | Ranking tiers | ❌ Raw position data | ✅ Bucket groups (1–3, 4–10, 11–20...) | | Position tracking | ❌ Manual comparison | ✅ Before/after diff with trackPositionChanges | | Dashboard output | ❌ Build from scratch | ✅ Structured DashboardData ready for any chart library | | TypeScript support | ❌ Untyped data | ✅ Full type coverage for all data structures |

Features

• GSC + audit data merge — mergeGscWithAudit joins Google Search Console page performance data (clicks, impressions, CTR, position) with @power-seo/audit results by normalized URL, producing PageInsight objects with both dimensions
• Pearson correlation — correlateScoreAndTraffic computes the Pearson correlation coefficient between audit scores and click counts across all merged page insights, returning the coefficient and a significance indicator
• Trend direction analysis — analyzeTrend detects whether a time series is trending up, down, or stable, with a rate-of-change value and a confidence score based on the linearity of the data
• Chart-ready trend lines — buildTrendLines converts raw data points into smoothed time-series arrays suitable for direct consumption by Recharts, Chart.js, or any other charting library
• Anomaly detection — detectAnomalies flags statistically significant spikes and drops in a time series using a configurable standard deviation threshold, returning annotated anomaly objects with timestamps and delta values
• Position bucket analysis — analyzeQueryRankings groups queries into four standard SERP ranking tiers: 1–3 (top spots), 4–10 (first page), 11–20 (second page), 21–100 (deep pages)
• Position change tracking — trackPositionChanges compares two ranking snapshots and produces a list of PositionChange objects showing which queries improved, declined, or are new/dropped
• Dashboard aggregation — buildDashboardData accepts raw GSC pages, GSC queries, and audit results and returns a structured DashboardData object containing: overview metrics, top pages by traffic, top queries by clicks, trend lines, and a prioritized issue list
• Normalized URL matching — URL normalization handles trailing slashes, protocol differences, and query string variations so that GSC URLs and audit URLs match correctly even when they are not identical strings
• Zero runtime dependencies — pure TypeScript computation
• Type-safe throughout — complete TypeScript types for all data structures

Comparison

| Feature | @power-seo/analytics | Looker Studio | GA4 | Custom scripts | | -------------------------- | :------------------: | :-----------: | :-----: | :------------: | | GSC + audit data merge | ✅ | ❌ | ❌ | Manual | | Pearson correlation | ✅ | ❌ | ❌ | Manual | | Trend direction analysis | ✅ | Partial | Partial | Manual | | Anomaly detection | ✅ | ❌ | Partial | Manual | | Position change tracking | ✅ | ❌ | ❌ | Manual | | Ranking bucket grouping | ✅ | ❌ | ❌ | Manual | | Dashboard-ready output | ✅ | ✅ | Partial | Manual | | Zero external dependencies | ✅ | ❌ | ❌ | — | | TypeScript-first | ✅ | ❌ | ❌ | — |

Installation

npm install @power-seo/analytics

yarn add @power-seo/analytics

pnpm add @power-seo/analytics

Quick Start

import { mergeGscWithAudit, buildDashboardData } from '@power-seo/analytics';

const dashboard = buildDashboardData({
  gscPages: [
    { url: '/blog/react-seo', clicks: 1240, impressions: 18500, ctr: 0.067, position: 4.2 },
    { url: '/blog/meta-tags', clicks: 380, impressions: 9200, ctr: 0.041, position: 8.7 },
    { url: '/blog/seo-audit', clicks: 55, impressions: 3100, ctr: 0.018, position: 19.1 },
  ],
  gscQueries: [
    { query: 'react seo guide', clicks: 820, impressions: 9400, ctr: 0.087, position: 3.1 },
    { query: 'meta tags react', clicks: 290, impressions: 5800, ctr: 0.05, position: 7.4 },
  ],
  auditResults: [
    { url: '/blog/react-seo', score: 88, issues: [] },
    { url: '/blog/meta-tags', score: 71, issues: [] },
    { url: '/blog/seo-audit', score: 44, issues: [] },
  ],
});

console.log(dashboard.overview.totalClicks); // 1675
console.log(dashboard.overview.averagePosition); // 10.67
console.log(dashboard.overview.averageAuditScore); // 67.7
console.log(dashboard.topPages[0].url); // '/blog/react-seo'

Usage

Merge GSC and Audit Data

mergeGscWithAudit normalizes and joins GSC page data with audit results. Pages that exist in one set but not the other are included with null values for the missing dimension.

import { mergeGscWithAudit } from '@power-seo/analytics';
import type { GscPageData, AuditSnapshot, PageInsight } from '@power-seo/analytics';

const gscPages: GscPageData[] = [
  {
    url: 'https://example.com/blog/post-1',
    clicks: 850,
    impressions: 12000,
    ctr: 0.071,
    position: 5.3,
  },
  {
    url: 'https://example.com/blog/post-2',
    clicks: 220,
    impressions: 6500,
    ctr: 0.034,
    position: 12.1,
  },
];

const auditResults = [
  { url: '/blog/post-1', score: 91, categories: { performance: 88, seo: 91 }, recommendations: [] },
  {
    url: '/blog/post-2',
    score: 63,
    categories: { performance: 55, seo: 63 },
    recommendations: ['Improve meta description', 'Add more internal links'],
  },
];

const insights: PageInsight[] = mergeGscWithAudit(gscPages, auditResults);

insights.forEach(({ url, clicks, position, auditScore }) => {
  console.log(`${url}: ${clicks} clicks @ pos ${position}, score=${auditScore ?? 'N/A'}`);
});

Correlation Analysis

correlateScoreAndTraffic answers the core question: does better audit score correlate with more traffic?

import { mergeGscWithAudit, correlateScoreAndTraffic } from '@power-seo/analytics';

const insights = mergeGscWithAudit(gscPages, auditResults);
const result = correlateScoreAndTraffic(insights);

console.log(`Pearson r: ${result.correlation.toFixed(3)}`);
// e.g. 0.741 — strong positive correlation

if (result.correlation > 0.5) {
  console.log('Strong positive relationship: improving audit scores tends to increase traffic');
}

// Top pages with high traffic but low scores
console.log(
  'Quick wins:',
  result.topOpportunities.map((p) => p.url),
);

Trend Analysis

import { analyzeTrend, buildTrendLines } from '@power-seo/analytics';
import type { TrendPoint, TrendAnalysis } from '@power-seo/analytics';

const weeklyClicks: TrendPoint[] = [
  { date: '2026-01-05', value: 1200 },
  { date: '2026-01-12', value: 1350 },
  { date: '2026-01-19', value: 1280 },
  { date: '2026-01-26', value: 1480 },
  { date: '2026-02-02', value: 1620 },
  { date: '2026-02-09', value: 1590 },
];

const trend: TrendAnalysis = analyzeTrend(weeklyClicks);
console.log(trend.trend); // 'improving' | 'declining' | 'stable'
console.log(trend.change); // % change from first to last, e.g. 32.5
console.log(trend.metric); // name of metric, e.g. 'value'

// Build chart-ready trend line data from audit history
const auditSnapshots: AuditSnapshot[] = [
  { date: '2026-01-01', url: '/page', score: 75, categories: { performance: 85, seo: 72 } },
  // more snapshots...
];
const trendLines = buildTrendLines(auditSnapshots);
// { overall: TrendAnalysis, performance: TrendAnalysis, seo: TrendAnalysis }

Anomaly Detection

import { detectAnomalies } from '@power-seo/analytics';

const dailyImpressions: TrendPoint[] = [
  { date: '2026-02-01', value: 8500 },
  { date: '2026-02-02', value: 8900 },
  { date: '2026-02-03', value: 8700 },
  { date: '2026-02-04', value: 8600 },
  { date: '2026-02-05', value: 24800 }, // spike — content went viral?
  { date: '2026-02-06', value: 9100 },
  { date: '2026-02-07', value: 2100 }, // drop — server issue?
  { date: '2026-02-08', value: 8800 },
];

const anomalies = detectAnomalies(dailyImpressions, 2.0);
anomalies.forEach(({ date, value }) => {
  const mean = dailyImpressions.reduce((s, p) => s + p.value, 0) / dailyImpressions.length;
  const delta = value - mean;
  const type = delta > 0 ? 'spike' : 'drop';
  console.log(`${date}: ${type} anomaly — value=${value}, delta=${delta.toFixed(0)} from baseline`);
});
// 2026-02-05: spike anomaly — value=24800, delta=16156 from baseline
// 2026-02-07: drop anomaly — value=2100, delta=-6514 from baseline

Ranking Analysis

import { analyzeQueryRankings } from '@power-seo/analytics';
import type { GscQueryData, RankingAnalysis } from '@power-seo/analytics';

const queries: GscQueryData[] = [
  { query: 'react seo', clicks: 820, impressions: 9400, ctr: 0.087, position: 2.1 },
  { query: 'seo audit tool', clicks: 340, impressions: 6200, ctr: 0.055, position: 6.8 },
  { query: 'meta tags guide', clicks: 180, impressions: 4800, ctr: 0.038, position: 14.3 },
  { query: 'sitemap generator', clicks: 30, impressions: 2100, ctr: 0.014, position: 28.7 },
  { query: 'seo typescript', clicks: 5, impressions: 1200, ctr: 0.004, position: 67.2 },
];

const analysis: RankingAnalysis = analyzeQueryRankings(queries);

analysis.buckets.forEach((bucket) => {
  console.log(`Position ${bucket.range}: ${bucket.count} queries`);
});

// Quick-win opportunities: ranked 4-20 with good impressions (strikingDistance)
const quickWins = analysis.strikingDistance.filter((q) => q.impressions > 2000);
console.log(
  'Quick-win queries:',
  quickWins.map((q) => q.query),
);

Position Change Tracking

import { trackPositionChanges } from '@power-seo/analytics';
import type { PositionChange } from '@power-seo/analytics';

const previousSnapshot: GscQueryData[] = [
  { query: 'react seo guide', clicks: 320, impressions: 8200, ctr: 0.039, position: 8.4 },
  { query: 'seo audit', clicks: 45, impressions: 1900, ctr: 0.024, position: 22.0 },
];

const currentSnapshot: GscQueryData[] = [
  { query: 'react seo guide', clicks: 580, impressions: 9800, ctr: 0.059, position: 5.1 },
  { query: 'seo audit', clicks: 88, impressions: 2200, ctr: 0.04, position: 14.3 },
  { query: 'seo typescript', clicks: 12, impressions: 800, ctr: 0.015, position: 31.0 },
];

const changes: PositionChange[] = trackPositionChanges(currentSnapshot, previousSnapshot);
changes.forEach(({ query, previousPosition, currentPosition, change }) => {
  const direction = change > 0 ? '↑' : change < 0 ? '↓' : '→';
  console.log(`${direction} "${query}": ${previousPosition} → ${currentPosition}`);
});
// ↑ "react seo guide": 8.4 → 5.1
// ↑ "seo audit": 22.0 → 14.3

Dashboard Data

import { buildDashboardData } from '@power-seo/analytics';
import type { DashboardInput, DashboardData } from '@power-seo/analytics';

const dashboard: DashboardData = buildDashboardData({
  gscPages: allGscPages,
  gscQueries: allGscQueries,
  auditResults: allAuditResults,
  auditHistory: allAuditSnapshots,
});

// Overview metrics
console.log(dashboard.overview.totalClicks);
console.log(dashboard.overview.totalImpressions);
console.log(dashboard.overview.averageCtr);
console.log(dashboard.overview.averagePosition);
console.log(dashboard.overview.averageAuditScore);

// Top pages by clicks
dashboard.topPages.forEach(({ url, clicks, auditScore }) =>
  console.log(`${url}: ${clicks} clicks, score=${auditScore ?? 'N/A'}`),
);

// Top queries
dashboard.topQueries.forEach(({ query, clicks, position }) =>
  console.log(`"${query}": ${clicks} clicks @ position ${position.toFixed(1)}`),
);

// Trend lines ready for Recharts / Chart.js
dashboard.trendLines; // TrendPoint[]

// Recommended issues — deduplicated and prioritized
dashboard.issues.forEach((issue) => console.log(`Issue: ${issue}`));

API Reference

mergeGscWithAudit(gscData, auditResults)

| Parameter | Type | Default | Description | | -------------- | --------------- | -------- | ---------------------------------------------------------- | | gscData | GscPageData[] | required | Google Search Console page performance data | | auditResults | AuditData[] | required | Audit results with URL, score, categories, recommendations |

Returns PageInsight[] — merged records keyed by normalized URL with opportunities identified.

correlateScoreAndTraffic(insights)

| Parameter | Type | Default | Description | | ---------- | --------------- | -------- | --------------------------------------------------------- | | insights | PageInsight[] | required | Merged page insights with both audit score and click data |

Returns { correlation: number; topOpportunities: PageInsight[] } — Pearson correlation coefficient and highest-opportunity pages (high traffic, low score).

analyzeTrend(points, metric?)

| Parameter | Type | Default | Description | | --------- | -------------- | -------- | ---------------------------------------------------- | | points | TrendPoint[] | required | Time-ordered { date: string; value: number } array | | metric | string | 'value' | Name of the metric being analyzed |

Returns TrendAnalysis: { metric: string; trend: TrendDirection; change: number; points: TrendPoint[] }. Trend is determined by linear regression slope; change is percentage difference from first to last value.

buildTrendLines(snapshots)

| Parameter | Type | Default | Description | | ----------- | ----------------- | -------- | --------------------------------------------------- | | snapshots | AuditSnapshot[] | required | Audit snapshots with date, score, and category data |

Returns Record<string, TrendAnalysis> — includes 'overall' trend plus per-category trends (e.g., 'performance', 'seo').

detectAnomalies(points, threshold?)

| Parameter | Type | Default | Description | | ----------- | -------------- | -------- | --------------------------------------------------- | | points | TrendPoint[] | required | Time-ordered data points | | threshold | number | 2.0 | Standard deviation multiplier for anomaly detection |

Returns TrendPoint[] — data points that exceed the threshold (standard deviation multiple of the mean). Caller can determine if spike or drop based on mean.

analyzeQueryRankings(queries)

| Parameter | Type | Default | Description | | --------- | ---------------- | -------- | ----------------------------------- | | queries | GscQueryData[] | required | GSC query data with position values |

Returns RankingAnalysis: { totalQueries: number; buckets: RankingBucket[]; strikingDistance: GscQueryData[] }. Buckets are: 1–3, 4–10, 11–20, 21–100 (positions). Striking distance identifies 4–20 ranked queries with highest impressions for quick-win targeting.

trackPositionChanges(current, previous)

| Parameter | Type | Default | Description | | ---------- | ---------------- | -------- | ---------------------------------------- | | current | GscQueryData[] | required | Ranking snapshot from the later period | | previous | GscQueryData[] | required | Ranking snapshot from the earlier period |

Returns PositionChange[]: { query: string; previousPosition: number; currentPosition: number; change: number; impressionChange: number }. Positive change indicates improvement (lower position number).

buildDashboardData(input)

| Parameter | Type | Default | Description | | -------------------- | ----------------- | ------- | --------------------------------------------------- | | input.gscPages | GscPageData[] | [] | GSC page performance data | | input.gscQueries | GscQueryData[] | [] | GSC query performance data | | input.auditResults | AuditData[] | [] | Audit results for correlation and issue aggregation | | input.auditHistory | AuditSnapshot[] | [] | Audit history for trend analysis |

Returns DashboardData: aggregated overview, top pages/queries, trend lines per category, and recommended issues.

Types

import type {
  GscPageData, // { url, clicks, impressions, ctr, position, date? }
  GscQueryData, // { query, clicks, impressions, ctr, position, date? }
  AuditSnapshot, // { date, url, score, categories }
  TrendPoint, // { date: string; value: number }
  TrendDirection, // 'improving' | 'declining' | 'stable'
  TrendAnalysis, // { metric, trend, change, points }
  PageInsight, // { url, gscMetrics?, auditScore?, auditCategories?, opportunities }
  RankingBucket, // { range: string; count: number; queries: GscQueryData[] }
  RankingAnalysis, // { totalQueries, buckets: RankingBucket[], strikingDistance }
  PositionChange, // { query, previousPosition, currentPosition, change, impressionChange }
  DashboardInput, // { gscPages?, gscQueries?, auditResults?, auditHistory? }
  DashboardOverview, // { totalClicks, totalImpressions, averageCtr, averagePosition, averageAuditScore, totalPages }
  DashboardData, // { overview, topPages, topQueries, trendLines: Record<string, TrendAnalysis>, issues: string[] }
} from '@power-seo/analytics';

Use Cases

• SEO dashboards — feed buildDashboardData output directly into Recharts, Chart.js, or any admin UI
• Monthly reporting — automate correlation analysis to demonstrate SEO ROI to stakeholders
• Quick-win identification — use position bucket analysis to prioritize pages ranked 11–20 for content updates
• Algorithm update monitoring — use anomaly detection to flag traffic drops aligned with Google algorithm updates
• Site migration tracking — compare position snapshots before and after migration with trackPositionChanges

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Zero external runtime dependencies — pure computational logic; no external API calls
• Framework-agnostic — works in any JavaScript environment: Next.js, Remix, Node.js, Edge
• SSR compatible — no browser-specific APIs; safe for server-side or CLI usage
• Edge runtime safe — no Node.js-specific APIs; runs in Cloudflare Workers, Vercel Edge
• Tree-shakeable — "sideEffects": false with named exports per function
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage

Supply Chain Security

• No install scripts (postinstall, preinstall)
• No runtime network access
• No eval or dynamic code execution
• CI-signed builds — all releases published via verified github.com/CyberCraftBD/power-seo workflow
• Safe for SSR, Edge, and server environments

The @power-seo Ecosystem

All 17 packages are independently installable — use only what you need.

| Package | Install | Description | | ------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------- | | @power-seo/core | npm i @power-seo/core | Framework-agnostic utilities, types, validators, and constants | | @power-seo/react | npm i @power-seo/react | React SEO components — meta, Open Graph, Twitter Card, breadcrumbs | | @power-seo/meta | npm i @power-seo/meta | SSR meta helpers for Next.js App Router, Remix v2, and generic SSR | | @power-seo/schema | npm i @power-seo/schema | Type-safe JSON-LD structured data — 23 builders + 22 React components | | @power-seo/content-analysis | npm i @power-seo/content-analysis | Yoast-style SEO content scoring engine with React components | | @power-seo/readability | npm i @power-seo/readability | Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI | | @power-seo/preview | npm i @power-seo/preview | SERP, Open Graph, and Twitter/X Card preview generators | | @power-seo/sitemap | npm i @power-seo/sitemap | XML sitemap generation, streaming, index splitting, and validation | | @power-seo/redirects | npm i @power-seo/redirects | Redirect engine with Next.js, Remix, and Express adapters | | @power-seo/links | npm i @power-seo/links | Link graph analysis — orphan detection, suggestions, equity scoring | | @power-seo/audit | npm i @power-seo/audit | Full SEO audit engine — meta, content, structure, performance rules | | @power-seo/images | npm i @power-seo/images | Image SEO — alt text, lazy loading, format analysis, image sitemaps | | @power-seo/ai | npm i @power-seo/ai | LLM-agnostic AI prompt templates and parsers for SEO tasks | | @power-seo/analytics | npm i @power-seo/analytics | Merge GSC + audit data, trend analysis, ranking insights, dashboard | | @power-seo/search-console | npm i @power-seo/search-console | Google Search Console API — OAuth2, service account, URL inspection | | @power-seo/integrations | npm i @power-seo/integrations | Semrush and Ahrefs API clients with rate limiting and pagination | | @power-seo/tracking | npm i @power-seo/tracking | GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management |

About CyberCraft Bangladesh

CyberCraft Bangladesh is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.

© 2026 CyberCraft Bangladesh · Released under the MIT License