Skip to content

📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

Migrate SEO analytics to v2 API

Blue Mouse3be9b6654d4d
diff --git a/backend/apps/cloud/src/analytics/analytics.controller.ts b/backend/apps/cloud/src/analytics/analytics.controller.ts
index 76f237689..ea22a6824 100644
--- a/backend/apps/cloud/src/analytics/analytics.controller.ts
+++ b/backend/apps/cloud/src/analytics/analytics.controller.ts
@@ -50,7 +50,7 @@ import { DEFAULT_TIMEZONE } from '../user/entities/user.entity'
import { AuthenticationGuard } from '../auth/guards/authentication.guard'
import { PageviewsDto } from './dto/pageviews.dto'
import { EventsDto } from './dto/events.dto'
-import { GetDataDto, ChartRenderMode, TimeBucketType } from './dto/getData.dto'
+import { GetDataDto, ChartRenderMode } from './dto/getData.dto'
import { GetCustomEventMetadata } from './dto/get-custom-event-meta.dto'
import { GetPagePropertyMetaDto } from './dto/get-page-property-meta.dto'
import { GetJourneysDto } from './dto/get-journeys.dto'
@@ -109,7 +109,7 @@ import { LiveVisitorsDto } from './dto/live-visitors.dto'
import { GetHeartbeatStatsDto } from './dto/get-heartbeat-stats'
import { GetKeywordsDto } from './dto/get-keywords.dto'
import { GetBotStatsDto } from './dto/get-bot-stats.dto'
-import { GSCService } from '../project/gsc.service'
+import { GSC_ALL_TIME_DAYS, GSCService } from '../project/gsc.service'
import { GetProfileIdDto, GetSessionIdDto } from './dto/get-id.dto'
import { ExperimentService } from '../experiment/experiment.service'
import {
@@ -129,9 +129,6 @@ const BOT_RESPONSE = { message: 'Bot traffic detected, request is ignored' }
const ONLINE_VISITORS_WINDOW_MINUTES = 5 // minutes
-// Maximum range for "all time" GSC queries (~16 months, GSC's data retention)
-const GSC_ALL_TIME_DAYS = 480
-
// Performance object validator: none of the values cannot be bigger than 1000 * 60 * 5 (5 minutes) and are >= 0
const MAX_PERFORMANCE_VALUE = 1000 * 60 * 5
const isPerformanceValid = (perf: any) => {
@@ -1196,139 +1193,6 @@ export class AnalyticsController {
return { keywords }
}
- @Get('gsc-dashboard')
- @Auth(true, true)
- async getGSCDashboard(
- @Query() data: GetKeywordsDto,
- @CurrentUserId() uid: string,
- @Headers() headers: { 'x-password'?: string },
- ) {
- const {
- pid,
- period,
- from,
- to,
- timezone = DEFAULT_TIMEZONE,
- timeBucket,
- filters,
- } = data
-
- await this.analyticsService.checkProjectAccess(
- pid,
- uid,
- headers['x-password'],
- )
-
- await this.analyticsService.checkBillingAccess(pid)
-
- const defaultTimeBucket = ['1h', 'today', 'yesterday', '1d'].includes(
- period,
- )
- ? TimeBucketType.HOUR
- : TimeBucketType.DAY
- const finalTimeBucket = (timeBucket || defaultTimeBucket) as TimeBucketType
- let groupTimeBucket: TimeBucketType | null = finalTimeBucket
- if (period === 'all' || period === 'custom') {
- groupTimeBucket = null
- }
-
- this.logger.log(
- `pid: ${pid}, period: ${period}, timeBucket: ${finalTimeBucket}, filters: ${filters}`,
- 'GET /analytics/gsc-dashboard',
- )
-
- const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined
-
- const safeTimezone = this.analyticsService.getSafeTimezone(timezone)
- const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(
- from,
- to,
- groupTimeBucket,
- period,
- safeTimezone,
- diff,
- )
-
- return this.gscService.getDashboard(
- pid,
- groupFrom,
- groupTo,
- finalTimeBucket,
- filters,
- )
- }
-
- @Get('gsc-details')
- @Auth(true, true)
- async getGSCDetails(
- @Query() data: GetKeywordsDto,
- @CurrentUserId() uid: string,
- @Headers() headers: { 'x-password'?: string },
- ) {
- const {
- pid,
- period,
- from,
- to,
- timezone = DEFAULT_TIMEZONE,
- page,
- query,
- } = data
-
- this.logger.log(
- `pid: ${pid}, period: ${period}, page: ${page}, query: ${query}`,
- 'GET /analytics/gsc-details',
- )
-
- await this.analyticsService.checkProjectAccess(
- pid,
- uid,
- headers['x-password'],
- )
-
- await this.analyticsService.checkBillingAccess(pid)
-
- const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined
-
- const safeTimezone = this.analyticsService.getSafeTimezone(timezone)
- const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(
- from,
- to,
- null,
- period,
- safeTimezone,
- diff,
- )
-
- if (page) {
- const keywords = await this.gscService.getKeywords(
- pid,
- groupFrom,
- groupTo,
- 50,
- 0,
- undefined,
- page,
- )
- return { type: 'queries', data: keywords }
- }
-
- if (query) {
- const pages = await this.gscService.getTopPages(
- pid,
- groupFrom,
- groupTo,
- 50,
- 0,
- undefined,
- query,
- )
- return { type: 'pages', data: pages }
- }
-
- return { type: 'none', data: [] }
- }
-
@Get('birdseye')
@Auth(true, true)
// returns overall short statistics per project
diff --git a/backend/apps/cloud/src/analytics/analytics.module.ts b/backend/apps/cloud/src/analytics/analytics.module.ts
index ae5fb10ae..f0f0a817b 100644
--- a/backend/apps/cloud/src/analytics/analytics.module.ts
+++ b/backend/apps/cloud/src/analytics/analytics.module.ts
@@ -22,6 +22,7 @@ import {
} from './session-replay-export.service'
import { SessionReplayExportProcessor } from './session-replay-export.processor'
import { AnalyticsV2Service } from './v2/analytics-v2.service'
+import { SeoV2Service } from './v2/seo-v2.service'
import { TrafficV2Controller } from './v2/controllers/traffic-v2.controller'
import { PerformanceV2Controller } from './v2/controllers/performance-v2.controller'
import { CaptchaV2Controller } from './v2/controllers/captcha-v2.controller'
@@ -29,6 +30,7 @@ import { ErrorsV2Controller } from './v2/controllers/errors-v2.controller'
import { SessionsV2Controller } from './v2/controllers/sessions-v2.controller'
import { ProfilesV2Controller } from './v2/controllers/profiles-v2.controller'
import { ProjectV2Controller } from './v2/controllers/project-v2.controller'
+import { SeoV2Controller } from './v2/controllers/seo-v2.controller'
@Module({
imports: [
@@ -43,6 +45,7 @@ import { ProjectV2Controller } from './v2/controllers/project-v2.controller'
providers: [
AnalyticsService,
AnalyticsV2Service,
+ SeoV2Service,
BotDetectionService,
SaltService,
SessionReplayS3Service,
@@ -62,6 +65,7 @@ import { ProjectV2Controller } from './v2/controllers/project-v2.controller'
SessionsV2Controller,
ProfilesV2Controller,
ProjectV2Controller,
+ SeoV2Controller,
],
})
export class AnalyticsModule {}
diff --git a/backend/apps/cloud/src/analytics/protection/public-project-cache.interceptor.ts b/backend/apps/cloud/src/analytics/protection/public-project-cache.interceptor.ts
index a108983b4..f82b44cf0 100644
--- a/backend/apps/cloud/src/analytics/protection/public-project-cache.interceptor.ts
+++ b/backend/apps/cloud/src/analytics/protection/public-project-cache.interceptor.ts
@@ -33,8 +33,6 @@ const CACHEABLE_ROUTES = new Set([
'funnel-sessions',
'custom-events',
'keywords',
- 'gsc-dashboard',
- 'gsc-details',
])
/**
diff --git a/backend/apps/cloud/src/analytics/v2/__tests__/seo.mapper.spec.ts b/backend/apps/cloud/src/analytics/v2/__tests__/seo.mapper.spec.ts
new file mode 100644
index 000000000..d90e11b99
--- /dev/null
+++ b/backend/apps/cloud/src/analytics/v2/__tests__/seo.mapper.spec.ts
@@ -0,0 +1,210 @@
+import { TimeBucketType } from '../../dto/getData.dto'
+import {
+ bucketSeoDateSeries,
+ gscCountryToAlpha2,
+ mapSeoBreakdownRows,
+ mapSeoSummary,
+ mapSeoTimeseries,
+ SeoDateSeriesEntry,
+} from '../mappers/seo.mapper'
+
+const day = (
+ date: string,
+ clicks: number,
+ impressions: number,
+ position: number,
+): SeoDateSeriesEntry => ({
+ date,
+ clicks,
+ impressions,
+ position,
+ ctr: impressions > 0 ? (clicks / impressions) * 100 : 0,
+})
+
+describe('gscCountryToAlpha2', () => {
+ it('converts Search Console alpha-3 to the alpha-2 the rest of v2 uses', () => {
+ expect(gscCountryToAlpha2('usa')).toBe('US')
+ expect(gscCountryToAlpha2('deu')).toBe('DE')
+ expect(gscCountryToAlpha2('ukr')).toBe('UA')
+ })
+
+ it('passes through anything it cannot map rather than dropping the row', () => {
+ expect(gscCountryToAlpha2('zzz')).toBe('ZZZ')
+ expect(gscCountryToAlpha2('')).toBe('')
+ })
+})
+
+describe('mapSeoBreakdownRows', () => {
+ it("reads getKeywords' `count` as clicks", () => {
+ expect(
+ mapSeoBreakdownRows(
+ 'query',
+ [
+ {
+ name: 'swetrix',
+ count: 12,
+ impressions: 400,
+ ctr: 3,
+ position: 4.2,
+ },
+ ],
+ ['clicks', 'impressions', 'ctr', 'position'],
+ ),
+ ).toEqual([
+ { value: 'swetrix', clicks: 12, impressions: 400, ctr: 3, position: 4.2 },
+ ])
+ })
+
+ it('reads the label field each per-dimension getter returns', () => {
+ expect(
+ mapSeoBreakdownRows('page', [{ page: '/blog', clicks: 5 }], ['clicks']),
+ ).toEqual([{ value: '/blog', clicks: 5 }])
+
+ expect(
+ mapSeoBreakdownRows(
+ 'device',
+ [{ device: 'mobile', clicks: 3 }],
+ ['clicks'],
+ ),
+ ).toEqual([{ value: 'mobile', clicks: 3 }])
+ })
+
+ it('normalises country rows to alpha-2', () => {
+ expect(
+ mapSeoBreakdownRows(
+ 'country',
+ [{ country: 'usa', clicks: 9 }],
+ ['clicks'],
+ ),
+ ).toEqual([{ value: 'US', clicks: 9 }])
+ })
+
+ it('only emits the requested metrics', () => {
+ expect(
+ mapSeoBreakdownRows(
+ 'query',
+ [{ name: 'a', count: 1, impressions: 2, ctr: 50, position: 1 }],
+ ['clicks'],
+ ),
+ ).toEqual([{ value: 'a', clicks: 1 }])
+ })
+
+ it('defaults missing values to zero rather than emitting NaN', () => {
+ expect(
+ mapSeoBreakdownRows('query', [{ name: 'a' }], ['clicks', 'position']),
+ ).toEqual([{ value: 'a', clicks: 0, position: 0 }])
+ })
+})
+
+describe('mapSeoSummary', () => {
+ it('reports the absolute change between periods, matching the other v2 summaries', () => {
+ expect(
+ mapSeoSummary(
+ { clicks: 120, impressions: 3000, ctr: 4, position: 8.1 },
+ { clicks: 100, impressions: 2500, ctr: 4.5, position: 9.4 },
+ ),
+ ).toEqual({
+ current: { clicks: 120, impressions: 3000, ctr: 4, position: 8.1 },
+ previous: { clicks: 100, impressions: 2500, ctr: 4.5, position: 9.4 },
+ change: { clicks: 20, impressions: 500, ctr: -0.5, position: -1.3 },
+ })
+ })
+
+ it('treats a missing previous period as zeroes', () => {
+ const summary = mapSeoSummary(
+ { clicks: 10, impressions: 100, ctr: 10, position: 2 },
+ null,
+ )
+
+ expect(summary.previous).toEqual({
+ clicks: 0,
+ impressions: 0,
+ ctr: 0,
+ position: 0,
+ })
+ expect(summary.change.clicks).toBe(10)
+ })
+})
+
+describe('bucketSeoDateSeries', () => {
+ const series = [
+ day('2026-01-05', 10, 100, 10),
+ day('2026-01-20', 30, 300, 2),
+ day('2026-02-10', 5, 50, 4),
+ ]
+
+ it('leaves the native hour and day granularity untouched', () => {
+ expect(bucketSeoDateSeries(series, TimeBucketType.DAY)).toBe(series)
+ expect(bucketSeoDateSeries(series, TimeBucketType.HOUR)).toBe(series)
+ })
+
+ it('sums clicks and impressions into month buckets', () => {
+ const [january, february] = bucketSeoDateSeries(
+ series,
+ TimeBucketType.MONTH,
+ )
+
+ expect(january.date).toBe('2026-01-01')
+ expect(january.clicks).toBe(40)
+ expect(january.impressions).toBe(400)
+ expect(february.date).toBe('2026-02-01')
+ expect(february.clicks).toBe(5)
+ })
+
+ it('recomputes ctr from the bucket totals rather than averaging it', () => {
+ const [january] = bucketSeoDateSeries(series, TimeBucketType.MONTH)
+ // 40 clicks / 400 impressions, not the mean of the two daily CTRs.
+ expect(january.ctr).toBe(10)
+ })
+
+ it('averages position weighted by impressions', () => {
+ const [january] = bucketSeoDateSeries(series, TimeBucketType.MONTH)
+ // (10*100 + 2*300) / 400 = 4, whereas a plain mean would give 6.
+ expect(january.position).toBe(4)
+ })
+
+ it('rolls a whole year up into one bucket', () => {
+ const yearly = bucketSeoDateSeries(series, TimeBucketType.YEAR)
+
+ expect(yearly).toHaveLength(1)
+ expect(yearly[0].date).toBe('2026-01-01')
+ expect(yearly[0].clicks).toBe(45)
+ })
+
+ it('reports zeroed rates for a bucket with no impressions', () => {
+ const [bucket] = bucketSeoDateSeries(
+ [day('2026-01-05', 0, 0, 0)],
+ TimeBucketType.MONTH,
+ )
+
+ expect(bucket.ctr).toBe(0)
+ expect(bucket.position).toBe(0)
+ })
+})
+
+describe('mapSeoTimeseries', () => {
+ it('emits ISO timestamps in the requested timezone', () => {
+ const [row] = mapSeoTimeseries(
+ [day('2026-01-05', 10, 100, 3)],
+ ['clicks'],
+ 'Europe/Kyiv',
+ )
+
+ expect(row.timestamp).toBe('2026-01-05T00:00:00+02:00')
+ expect(row.clicks).toBe(10)
+ })
+
+ it('only emits the requested metrics', () => {
+ const [row] = mapSeoTimeseries(
+ [day('2026-01-05', 10, 100, 3)],
+ ['clicks', 'position'],
+ 'UTC',
+ )
+
+ expect(Object.keys(row).sort()).toEqual(['clicks', 'position', 'timestamp'])
+ })
+
+ it('drops rows Search Console returned without a date', () => {
+ expect(mapSeoTimeseries([day('', 1, 1, 1)], ['clicks'], 'UTC')).toEqual([])
+ })
+})
diff --git a/backend/apps/cloud/src/analytics/v2/__tests__/seo.registry.spec.ts b/backend/apps/cloud/src/analytics/v2/__tests__/seo.registry.spec.ts
new file mode 100644
index 000000000..145d9407b
--- /dev/null
+++ b/backend/apps/cloud/src/analytics/v2/__tests__/seo.registry.spec.ts
@@ -0,0 +1,134 @@
+import { UnprocessableEntityException } from '@nestjs/common'
+
+import { V2Filter } from '../query/filters.translator'
+import {
+ getDefaultSeoMetrics,
+ getSeoBreakdownDimension,
+ getSeoMetric,
+ listSeoDimensions,
+ parseSeoMetricsParam,
+ toGscFiltersJson,
+ validateSeoFilters,
+ V2_SEO_DIMENSIONS,
+} from '../registry/seo'
+
+const filter = (overrides: Partial<V2Filter> = {}): V2Filter =>
+ ({
+ dimension: 'country',
+ operator: 'is',
+ value: 'US',
+ ...overrides,
+ }) as V2Filter
+
+describe('seo dimension lookups', () => {
+ it('resolves every declared dimension to its Search Console name', () => {
+ expect(getSeoBreakdownDimension('query').gsc).toBe('query')
+ expect(getSeoBreakdownDimension('page').gsc).toBe('page')
+ expect(getSeoBreakdownDimension('country').gsc).toBe('country')
+ expect(getSeoBreakdownDimension('device').gsc).toBe('device')
+ })
+
+ it('rejects unknown dimensions with 422', () => {
+ expect(() => getSeoBreakdownDimension('nope')).toThrow(
+ UnprocessableEntityException,
+ )
+ // Valid for traffic, but Search Console reports nothing like it.
+ expect(() => getSeoBreakdownDimension('browser')).toThrow(
+ UnprocessableEntityException,
+ )
+ })
+
+ it('has unique api names', () => {
+ const names = listSeoDimensions().map((dimension) => dimension.api)
+ expect(new Set(names).size).toBe(names.length)
+ })
+
+ it('only maps onto dimensions Search Console actually serves', () => {
+ for (const dimension of V2_SEO_DIMENSIONS) {
+ expect(['query', 'page', 'country', 'device']).toContain(dimension.gsc)
+ }
+ })
+})
+
+describe('seo metric lookups', () => {
+ it('resolves metrics and rejects unknown ones', () => {
+ expect(getSeoMetric('clicks').api).toBe('clicks')
+ expect(() => getSeoMetric('visitors')).toThrow(UnprocessableEntityException)
+ })
+
+ it('returns all four metrics by default', () => {
+ expect(getDefaultSeoMetrics().map((metric) => metric.api)).toEqual([
+ 'clicks',
+ 'impressions',
+ 'ctr',
+ 'position',
+ ])
+ })
+
+ it('parses and dedupes the metrics CSV param', () => {
+ expect(
+ parseSeoMetricsParam('clicks, impressions,clicks').map(
+ (metric) => metric.api,
+ ),
+ ).toEqual(['clicks', 'impressions'])
+
+ expect(parseSeoMetricsParam(undefined).map((metric) => metric.api)).toEqual(
+ ['clicks', 'impressions', 'ctr', 'position'],
+ )
+
+ expect(() => parseSeoMetricsParam('bogus')).toThrow(
+ UnprocessableEntityException,
+ )
+ })
+})
+
+describe('validateSeoFilters', () => {
+ it('accepts scalar filters on known dimensions', () => {
+ const filters = [filter(), filter({ dimension: 'query', value: 'swetrix' })]
+ expect(validateSeoFilters(filters)).toBe(filters)
+ })
+
+ it('rejects filters on dimensions Search Console cannot filter by', () => {
+ expect(() =>
+ validateSeoFilters([filter({ dimension: 'browser' })]),
+ ).toThrow(UnprocessableEntityException)
+ })
+
+ it('rejects array values, which have no dimensionFilterGroups equivalent', () => {
+ expect(() => validateSeoFilters([filter({ value: ['US', 'DE'] })])).toThrow(
+ UnprocessableEntityException,
+ )
+ })
+
+ it('rejects null values, since Search Console reports no unset values', () => {
+ expect(() => validateSeoFilters([filter({ value: null })])).toThrow(
+ UnprocessableEntityException,
+ )
+ })
+})
+
+describe('toGscFiltersJson', () => {
+ it('renames query -> keywords, the key GSCService.parseFilters expects', () => {
+ const json = toGscFiltersJson([
+ filter({ dimension: 'query', value: 'swetrix' }),
+ ])
+
+ expect(JSON.parse(json)).toEqual([
+ { dimension: 'keywords', operator: 'is', value: 'swetrix' },
+ ])
+ })
+
+ it('leaves dimensions that already share a name alone', () => {
+ const json = toGscFiltersJson([
+ filter({ dimension: 'page', operator: 'contains', value: '/blog' }),
+ ])
+
+ expect(JSON.parse(json)).toEqual([
+ { dimension: 'page', operator: 'contains', value: '/blog' },
+ ])
+ })
+
+ it('returns undefined for no filters so no filter group is sent', () => {
+ expect(toGscFiltersJson([])).toBeUndefined()
+ })
+})
diff --git a/backend/apps/cloud/src/analytics/v2/controllers/project-v2.controller.ts b/backend/apps/cloud/src/analytics/v2/controllers/project-v2.controller.ts
index 48df6c494..bb3a81ff2 100644
--- a/backend/apps/cloud/src/analytics/v2/controllers/project-v2.controller.ts
+++ b/backend/apps/cloud/src/analytics/v2/controllers/project-v2.controller.ts
@@ -33,6 +33,7 @@ import {
V2FunnelSessionsQueryDto,
} from '../dto/project.dto'
import { V2ProjectParamsDto } from '../dto/v2-base.dto'
+import { SeoV2Service } from '../seo-v2.service'
@ApiTags('Analytics v2')
@ApiBearerAuth()
@@ -44,6 +45,7 @@ import { V2ProjectParamsDto } from '../dto/v2-base.dto'
export class ProjectV2Controller {
constructor(
private readonly analyticsV2Service: AnalyticsV2Service,
+ private readonly seoV2Service: SeoV2Service,
private readonly logger: AppLoggerService,
) {}
@@ -144,6 +146,12 @@ export class ProjectV2Controller {
headers['x-password'],
)
+ // SEO is served by the Search Console API rather than ClickHouse, so it
+ // keeps its own registry outside the sqlExpr-based one.
+ if (query.type === 'seo') {
+ return this.seoV2Service.getDimensions()
+ }
+
return this.analyticsV2Service.getDimensions(query.type || 'traffic')
}
diff --git a/backend/apps/cloud/src/analytics/v2/controllers/seo-v2.controller.ts b/backend/apps/cloud/src/analytics/v2/controllers/seo-v2.controller.ts
new file mode 100644
index 000000000..85ee82f0c
--- /dev/null
+++ b/backend/apps/cloud/src/analytics/v2/controllers/seo-v2.controller.ts
@@ -0,0 +1,202 @@
+import {
+ Controller,
+ Get,
+ Headers,
+ Param,
+ Query,
+ UseGuards,
+ UseInterceptors,
+ UsePipes,
+ ValidationPipe,
+} from '@nestjs/common'
+import {
+ ApiBearerAuth,
+ ApiOperation,
+ ApiSecurity,
+ ApiTags,
+} from '@nestjs/swagger'
+
+import { Auth } from '../../../auth/decorators'
+import { CurrentUserId } from '../../../auth/decorators/current-user-id.decorator'
+import { OptionalJwtAccessTokenGuard } from '../../../auth/guards'
+import { AuthenticationGuard } from '../../../auth/guards/authentication.guard'
+import { AppLoggerService } from '../../../logger/logger.service'
+import { AnalyticsReadGuard } from '../../protection/analytics-read.guard'
+import { CacheableAnalytics } from '../../protection/cacheable-analytics.decorator'
+import { PublicProjectCacheInterceptor } from '../../protection/public-project-cache.interceptor'
+import { AnalyticsV2Service } from '../analytics-v2.service'
+import {
+ V2SeoBreakdownDto,
+ V2SeoRangeDto,
+ V2SeoSummaryDto,
+ V2SeoTimeseriesDto,
+} from '../dto/seo.dto'
+import { V2ProjectParamsDto } from '../dto/v2-base.dto'
+import { SeoV2Service } from '../seo-v2.service'
+
+@ApiTags('Analytics v2')
+@ApiBearerAuth()
+@ApiSecurity('apiKey')
+@UseGuards(OptionalJwtAccessTokenGuard, AuthenticationGuard, AnalyticsReadGuard)
+@UseInterceptors(PublicProjectCacheInterceptor)
+@UsePipes(new ValidationPipe({ transform: true }))
+@Controller('v2/projects/:pid/seo')
+export class SeoV2Controller {
+ constructor(
+ private readonly seoV2Service: SeoV2Service,
+ private readonly analyticsV2Service: AnalyticsV2Service,
+ private readonly logger: AppLoggerService,
+ ) {}
+
+ @Get('status')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'Search Console connection status',
+ description:
+ 'Whether Google Search Console is connected for this project and which property is linked. The other seo endpoints return 409 until both are true.',
+ })
+ async getStatus(
+ @Param() { pid }: V2ProjectParamsDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/status')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getStatus(pid)
+ }
+
+ @Get('summary')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'SEO summary',
+ description:
+ 'Clicks, impressions, CTR and average position for the selected period, the previous period of the same length, and the change between them.',
+ })
+ async getSummary(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoSummaryDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/summary')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getSummary(pid, query)
+ }
+
+ @Get('timeseries')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'SEO timeseries',
+ description:
+ 'Selected SEO metrics grouped by time bucket, as rows of objects with ISO-8601 timestamps.',
+ })
+ async getTimeseries(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoTimeseriesDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/timeseries')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getTimeseries(pid, query)
+ }
+
+ @Get('breakdown')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'SEO breakdown',
+ description:
+ 'SEO metrics grouped by a single dimension (query, page, country, device), paginated. Rows are always ordered by clicks descending.',
+ })
+ async getBreakdown(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoBreakdownDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(
+ `pid: ${pid}, dimension: ${query.dimension}`,
+ 'GET /v2/projects/:pid/seo/breakdown',
+ )
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getBreakdown(pid, query)
+ }
+
+ @Get('branded-traffic')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'Branded vs non-branded traffic',
+ description:
+ "Clicks split by whether the search query contained one of the project's brand keywords. Skipped for ranges wider than 31 days.",
+ })
+ async getBrandedTraffic(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoRangeDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/branded-traffic')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getBrandedTraffic(pid, query)
+ }
+
+ @Get('positions')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'Search position analytics',
+ description:
+ 'Impressions bucketed by search position, and the daily count of ranking queries per position bucket. Skipped for ranges wider than 31 days.',
+ })
+ async getPositions(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoRangeDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/positions')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getPositions(pid, query)
+ }
+}
diff --git a/backend/apps/cloud/src/analytics/v2/dto/project.dto.ts b/backend/apps/cloud/src/analytics/v2/dto/project.dto.ts
index 44dddc3a9..e3cbc8dc5 100644
--- a/backend/apps/cloud/src/analytics/v2/dto/project.dto.ts
+++ b/backend/apps/cloud/src/analytics/v2/dto/project.dto.ts
@@ -77,15 +77,15 @@ export class V2FunnelSessionsQueryDto extends V2FunnelQueryDto {
export class V2DimensionsQueryDto {
@ApiProperty({
required: false,
- enum: ['traffic', 'performance', 'captcha', 'errors'],
+ enum: ['traffic', 'performance', 'captcha', 'errors', 'seo'],
default: 'traffic',
description: 'Data type to list dimensions and metrics for',
})
@IsOptional()
- @IsIn(['traffic', 'performance', 'captcha', 'errors'], {
+ @IsIn(['traffic', 'performance', 'captcha', 'errors', 'seo'], {
message: 'The provided type is incorrect',
})
- type?: 'traffic' | 'performance' | 'captcha' | 'errors'
+ type?: 'traffic' | 'performance' | 'captcha' | 'errors' | 'seo'
}
export class V2DimensionValuesParamsDto extends V2ProjectParamsDto {
diff --git a/backend/apps/cloud/src/analytics/v2/dto/seo.dto.ts b/backend/apps/cloud/src/analytics/v2/dto/seo.dto.ts
new file mode 100644
index 000000000..f8153b33a
--- /dev/null
+++ b/backend/apps/cloud/src/analytics/v2/dto/seo.dto.ts
@@ -0,0 +1,115 @@
+import { ApiProperty } from '@nestjs/swagger'
+import { Type } from 'class-transformer'
+import {
+ IsIn,
+ IsInt,
+ IsNotEmpty,
+ IsOptional,
+ IsString,
+ Max,
+ Min,
+} from 'class-validator'
+
+import { TimeBucketType } from '../../dto/getData.dto'
+import { SEO_SORT } from '../registry/seo'
+import { V2BaseQueryDto } from './v2-base.dto'
+
+const V2_SEO_MAX_BREAKDOWN_LIMIT = 100
+
+/**
+ * Search Console reports nothing below hourly granularity, so `minute` is
+ * excluded from the buckets a caller may ask for.
+ */
+export const V2_SEO_TIME_BUCKETS = [
+ TimeBucketType.HOUR,
+ TimeBucketType.DAY,
+ TimeBucketType.MONTH,
+ TimeBucketType.YEAR,
+] as const
+
+export type V2SeoTimeBucket = (typeof V2_SEO_TIME_BUCKETS)[number]
+
+export class V2SeoSummaryDto extends V2BaseQueryDto {}
+
+export class V2SeoRangeDto extends V2BaseQueryDto {}
+
+export class V2SeoTimeseriesDto extends V2BaseQueryDto {
+ @ApiProperty({
+ required: false,
+ enum: V2_SEO_TIME_BUCKETS,
+ description:
+ "Time bucket for grouping. One of: hour, day, month, year. Defaults to 'day', or 'hour' for intraday periods.",
+ })
+ @IsOptional()
+ @IsIn(V2_SEO_TIME_BUCKETS as readonly string[], {
+ message: `The provided timeBucket is incorrect. Search Console supports: ${V2_SEO_TIME_BUCKETS.join(', ')}`,
+ })
+ timeBucket?: V2SeoTimeBucket
+
+ @ApiProperty({
+ required: false,
+ description:
+ 'Comma-separated metric names to return. Defaults to clicks, impressions, ctr and position.',
+ example: 'clicks,impressions',
+ })
+ @IsOptional()
+ @IsString()
+ metrics?: string
+}
+
+export class V2SeoBreakdownDto extends V2BaseQueryDto {
+ @ApiProperty({
+ description:
+ 'Dimension to break down by. One of: query, page, country, device',
+ example: 'query',
+ })
+ @IsNotEmpty()
+ @IsString()
+ dimension: string
+
+ @ApiProperty({
+ required: false,
+ description:
+ 'Comma-separated metric names to compute per dimension value. Defaults to clicks, impressions, ctr and position.',
+ example: 'clicks,impressions',
+ })
+ @IsOptional()
+ @IsString()
+ metrics?: string
+
+ @ApiProperty({
+ required: false,
+ default: 30,
+ maximum: V2_SEO_MAX_BREAKDOWN_LIMIT,
+ description: 'Number of rows to return',
+ })
+ @IsOptional()
+ @Type(() => Number)
+ @IsInt()
+ @Min(1)
+ @Max(V2_SEO_MAX_BREAKDOWN_LIMIT)
+ limit?: number
+
+ @ApiProperty({
+ required: false,
+ default: 0,
+ description: 'Number of rows to skip (pagination)',
+ })
+ @IsOptional()
+ @Type(() => Number)
+ @IsInt()
+ @Min(0)
+ offset?: number
+
+ @ApiProperty({
+ required: false,
+ enum: [SEO_SORT],
+ default: SEO_SORT,
+ description: `Search Console orders rows by clicks descending and offers no sort control, so '${SEO_SORT}' is the only accepted value.`,
+ })
+ @IsOptional()
+ @IsIn([SEO_SORT], {
+ message: `Search Console always orders rows by clicks descending; omit 'sort' or pass '${SEO_SORT}'`,
+ })
+ sort?: string
+}
diff --git a/backend/apps/cloud/src/analytics/v2/mappers/seo.mapper.ts b/backend/apps/cloud/src/analytics/v2/mappers/seo.mapper.ts
new file mode 100644
index 000000000..efd1ab46c
--- /dev/null
+++ b/backend/apps/cloud/src/analytics/v2/mappers/seo.mapper.ts
@@ -0,0 +1,221 @@
+import countries from 'i18n-iso-countries'
+import dayjs from 'dayjs'
+
+import { TimeBucketType } from '../../dto/getData.dto'
+import { V2SeoGscDimension } from '../registry/seo'
+import { toIsoTimestamp, TimeseriesRow } from './timeseries.mapper'
+
+export interface SeoMetricValues {
+ clicks: number
+ impressions: number
+ ctr: number
+ position: number
+}
+
+export type SeoDateSeriesEntry = { date: string } & SeoMetricValues
+
+export interface SeoSummaryData {
+ current: SeoMetricValues
+ previous: SeoMetricValues
+ change: SeoMetricValues
+}
+
+const round = (value: unknown, precision: number): number => {
+ const number = Number(value)
+
+ if (!Number.isFinite(number)) {
+ return 0
+ }
+
+ const factor = 10 ** precision
+
+ return Math.round(number * factor) / factor
+}
+
+const toInteger = (value: unknown): number => Math.round(Number(value) || 0)
+
+/**
+ * Search Console reports countries as lowercase ISO 3166-1 alpha-3, while the
+ * rest of the v2 surface (and the `cc` column behind the traffic `country`
+ * dimension) uses uppercase alpha-2. Normalise so a `country` value means the
+ * same thing whichever data type produced it.
+ */
+export const gscCountryToAlpha2 = (country: string): string => {
+ const alpha2 = countries.alpha3ToAlpha2(String(country || '').toUpperCase())
+
+ return alpha2 || String(country || '').toUpperCase()
+}
+
+const EMPTY_METRICS: SeoMetricValues = {
+ clicks: 0,
+ impressions: 0,
+ ctr: 0,
+ position: 0,
+}
+
+const mapSeoMetricValues = (
+ values: Partial<SeoMetricValues> | null | undefined,
+): SeoMetricValues => ({
+ clicks: toInteger(values?.clicks),
+ impressions: toInteger(values?.impressions),
+ ctr: round(values?.ctr, 2),
+ position: round(values?.position, 2),
+})
+
+export const mapSeoSummary = (
+ current: Partial<SeoMetricValues> | null | undefined,
+ previous: Partial<SeoMetricValues> | null | undefined,
+): SeoSummaryData => {
+ const mappedCurrent = mapSeoMetricValues(current)
+ const mappedPrevious = previous ? mapSeoMetricValues(previous) : EMPTY_METRICS
+
+ return {
+ current: mappedCurrent,
+ previous: mappedPrevious,
+ change: {
+ clicks: mappedCurrent.clicks - mappedPrevious.clicks,
+ impressions: mappedCurrent.impressions - mappedPrevious.impressions,
+ ctr: round(mappedCurrent.ctr - mappedPrevious.ctr, 2),
+ position: round(mappedCurrent.position - mappedPrevious.position, 2),
+ },
+ }
+}
+
+/**
+ * A raw row as returned by one of the GSCService per-dimension getters. They
+ * disagree on the label field, and getKeywords calls its click count `count`.
+ */
+export interface GscBreakdownRow extends Partial<SeoMetricValues> {
+ name?: string
+ page?: string
+ country?: string
+ device?: string
+ count?: number
+}
+
+const readRowValue = (
+ dimension: V2SeoGscDimension,
+ row: GscBreakdownRow,
+): string => {
+ if (dimension === 'query') return row.name ?? ''
+ if (dimension === 'page') return row.page ?? ''
+ if (dimension === 'country') return gscCountryToAlpha2(row.country ?? '')
+
+ return row.device ?? ''
+}
+
+export const mapSeoBreakdownRows = (
+ dimension: V2SeoGscDimension,
+ rows: GscBreakdownRow[],
+ metrics: string[],
+): Record<string, unknown>[] =>
+ rows.map((row) => {
+ const values = mapSeoMetricValues({
+ clicks: row.clicks ?? row.count,
+ impressions: row.impressions,
+ ctr: row.ctr,
+ position: row.position,
+ })
+
+ const mapped: Record<string, unknown> = {
+ value: readRowValue(dimension, row),
+ }
+
+ for (const metric of metrics) {
+ mapped[metric] = values[metric as keyof SeoMetricValues]
+ }
+
+ return mapped
+ })
+
+const startOfBucket = (date: string, bucket: TimeBucketType): string => {
+ const parsed = dayjs(date)
+
+ if (bucket === TimeBucketType.MONTH) {
+ return parsed.startOf('month').format('YYYY-MM-DD')
+ }
+
+ if (bucket === TimeBucketType.YEAR) {
+ return parsed.startOf('year').format('YYYY-MM-DD')
+ }
+
+ return date
+}
+
+/**
+ * Search Console only serves hourly and daily rows, so wider buckets are rolled
+ * up here. Clicks and impressions sum; ctr is recomputed from the totals and
+ * position is averaged weighted by impressions, since neither is additive.
+ */
+export const bucketSeoDateSeries = (
+ series: SeoDateSeriesEntry[],
+ bucket: TimeBucketType,
+): SeoDateSeriesEntry[] => {
+ if (bucket !== TimeBucketType.MONTH && bucket !== TimeBucketType.YEAR) {
+ return series
+ }
+
+ const buckets = new Map<
+ string,
+ { clicks: number; impressions: number; weightedPosition: number }
+ >()
+ const orderedKeys: string[] = []
+
+ for (const entry of series) {
+ if (!entry.date) continue
+
+ const key = startOfBucket(entry.date, bucket)
+ const existing = buckets.get(key)
+
+ if (existing) {
+ existing.clicks += entry.clicks
+ existing.impressions += entry.impressions
+ existing.weightedPosition += entry.position * entry.impressions
+ } else {
+ orderedKeys.push(key)
+ buckets.set(key, {
+ clicks: entry.clicks,
+ impressions: entry.impressions,
+ weightedPosition: entry.position * entry.impressions,
+ })
+ }
+ }
+
+ return orderedKeys.map((key) => {
+ const entry = buckets.get(key)
+
+ return {
+ date: key,
+ clicks: Math.round(entry.clicks),
+ impressions: Math.round(entry.impressions),
+ ctr:
+ entry.impressions > 0
+ ? round((entry.clicks / entry.impressions) * 100, 2)
+ : 0,
+ position:
+ entry.impressions > 0
+ ? round(entry.weightedPosition / entry.impressions, 2)
+ : 0,
+ }
+ })
+}
+
+export const mapSeoTimeseries = (
+ series: SeoDateSeriesEntry[],
+ metrics: string[],
+ timezone: string,
+): TimeseriesRow[] =>
+ series
+ .filter((entry) => Boolean(entry.date))
+ .map((entry) => {
+ const values = mapSeoMetricValues(entry)
+ const row: TimeseriesRow = {
+ timestamp: toIsoTimestamp(entry.date, timezone),
+ }
+
+ for (const metric of metrics) {
+ row[metric] = values[metric as keyof SeoMetricValues]
+ }
+
+ return row
+ })
diff --git a/backend/apps/cloud/src/analytics/v2/registry/seo.ts b/backend/apps/cloud/src/analytics/v2/registry/seo.ts
new file mode 100644
index 000000000..7128783ee
--- /dev/null
+++ b/backend/apps/cloud/src/analytics/v2/registry/seo.ts
@@ -0,0 +1,193 @@
+import { UnprocessableEntityException } from '@nestjs/common'
+
+import { V2Filter } from '../query/filters.translator'
+
+/**
+ * SEO data is served by the Google Search Console API rather than ClickHouse,
+ * so it cannot join the column/sqlExpr registry in ./dimensions and ./metrics.
+ * These definitions mirror that registry's shape and lookup semantics to keep
+ * /v2/projects/:pid/seo/* consistent with the rest of the v2 surface.
+ */
+
+export type V2SeoGscDimension = 'query' | 'page' | 'country' | 'device'
+
+export interface V2SeoDimensionDef {
+ api: string
+ gsc: V2SeoGscDimension
+ description: string
+}
+
+export interface V2SeoMetricDef {
+ api: string
+ isDefault?: boolean
+ format: 'integer' | 'percent' | 'position'
+ description: string
+}
+
+export const V2_SEO_DIMENSIONS: V2SeoDimensionDef[] = [
+ {
+ api: 'query',
+ gsc: 'query',
+ description: 'Search query the site was surfaced for',
+ },
+ {
+ api: 'page',
+ gsc: 'page',
+ description: 'Landing page URL that appeared in search results',
+ },
+ {
+ api: 'country',
+ gsc: 'country',
+ description: 'Country the search was made from (ISO 3166-1 alpha-2 code)',
+ },
+ {
+ api: 'device',
+ gsc: 'device',
+ description: 'Device category the search was made on',
+ },
+]
+
+const V2_SEO_METRICS: V2SeoMetricDef[] = [
+ {
+ api: 'clicks',
+ isDefault: true,
+ format: 'integer',
+ description: 'Clicks through to the site from search results',
+ },
+ {
+ api: 'impressions',
+ isDefault: true,
+ format: 'integer',
+ description: 'Times a link to the site appeared in search results',
+ },
+ {
+ api: 'ctr',
+ isDefault: true,
+ format: 'percent',
+ description: 'Click-through rate, as a percentage of impressions',
+ },
+ {
+ api: 'position',
+ isDefault: true,
+ format: 'position',
+ description: 'Average position in search results',
+ },
+]
+
+export const listSeoDimensions = (): V2SeoDimensionDef[] => V2_SEO_DIMENSIONS
+
+export const listSeoMetrics = (): V2SeoMetricDef[] => V2_SEO_METRICS
+
+const findSeoDimension = (api: string): V2SeoDimensionDef | undefined =>
+ V2_SEO_DIMENSIONS.find((dimension) => dimension.api === api)
+
+export const getSeoBreakdownDimension = (api: string): V2SeoDimensionDef => {
+ const dimension = findSeoDimension(api)
+
+ if (!dimension) {
+ throw new UnprocessableEntityException(
+ `Unknown seo dimension '${api}'. Supported dimensions: ${V2_SEO_DIMENSIONS.map(
+ (d) => d.api,
+ ).join(', ')}`,
+ )
+ }
+
+ return dimension
+}
+
+export const getSeoMetric = (api: string): V2SeoMetricDef => {
+ const metric = V2_SEO_METRICS.find((m) => m.api === api)
+
+ if (!metric) {
+ throw new UnprocessableEntityException(
+ `Unknown seo metric '${api}'. Supported metrics: ${V2_SEO_METRICS.map(
+ (m) => m.api,
+ ).join(', ')}`,
+ )
+ }
+
+ return metric
+}
+
+export const getDefaultSeoMetrics = (): V2SeoMetricDef[] =>
+ V2_SEO_METRICS.filter((metric) => metric.isDefault)
+
+export const parseSeoMetricsParam = (
+ metrics: string | undefined,
+): V2SeoMetricDef[] => {
+ if (!metrics) {
+ return getDefaultSeoMetrics()
+ }
+
+ const names = [
+ ...new Set(
+ metrics
+ .split(',')
+ .map((name) => name.trim())
+ .filter(Boolean),
+ ),
+ ]
+
+ if (names.length === 0) {
+ return getDefaultSeoMetrics()
+ }
+
+ return names.map((name) => getSeoMetric(name))
+}
+
+/**
+ * Search Console orders rows by clicks descending and exposes no sort control,
+ * so this is the only ordering the seo breakdown can honour. It is accepted
+ * (rather than rejected outright) so callers can be explicit about it.
+ */
+export const SEO_SORT = 'clicks:desc'
+
+/**
+ * GSCService.parseFilters keys filters by their v1 URL names, where the keyword
+ * dimension is 'keywords'. v2 calls it 'query', after Search Console's own
+ * naming, so translate on the way down — the same v2 -> v1 hop the ClickHouse
+ * data types make through toV1FiltersJson.
+ */
+export const toGscFiltersJson = (filters: V2Filter[]): string | undefined => {
+ if (filters.length === 0) {
+ return undefined
+ }
+
+ return JSON.stringify(
+ filters.map((filter) => ({
+ ...filter,
+ dimension: filter.dimension === 'query' ? 'keywords' : filter.dimension,
+ })),
+ )
+}
+
+/**
+ * Search Console expresses filters as dimensionFilterGroups of scalar
+ * comparisons, so the array / null values the rest of v2 accepts have no
+ * equivalent here. Reject them rather than silently dropping the filter.
+ */
+export const validateSeoFilters = (filters: V2Filter[]): V2Filter[] => {
+ for (const filter of filters) {
+ if (!findSeoDimension(filter.dimension)) {
+ throw new UnprocessableEntityException(
+ `Unknown seo filter dimension '${filter.dimension}'. Supported dimensions: ${V2_SEO_DIMENSIONS.map(
+ (d) => d.api,
+ ).join(', ')}`,
+ )
+ }
+
+ if (Array.isArray(filter.value)) {
+ throw new UnprocessableEntityException(
+ `The seo filter on '${filter.dimension}' cannot take an array of values; Search Console only supports a single value per filter`,
+ )
+ }
+
+ if (filter.value === null) {
+ throw new UnprocessableEntityException(
+ `The seo filter on '${filter.dimension}' cannot take a null value; Search Console does not report unset dimension values`,
+ )
+ }
+ }
+
+ return filters
+}
diff --git a/backend/apps/cloud/src/analytics/v2/seo-v2.service.ts b/backend/apps/cloud/src/analytics/v2/seo-v2.service.ts
new file mode 100644
index 000000000..a8261e0a3
--- /dev/null
+++ b/backend/apps/cloud/src/analytics/v2/seo-v2.service.ts
@@ -0,0 +1,512 @@
+import {
+ BadRequestException,
+ ConflictException,
+ Injectable,
+ UnprocessableEntityException,
+} from '@nestjs/common'
+import dayjs from 'dayjs'
+import utc from 'dayjs/plugin/utc'
+
+import {
+ BrandedTrafficAnalytics,
+ GSC_ALL_TIME_DAYS,
+ GSCContext,
+ GSCService,
+ MAX_BRANDED_TRAFFIC_RANGE_DAYS,
+ MAX_FILTER_EXPRESSION_LENGTH,
+ MAX_FILTERS,
+ MAX_POSITION_ANALYTICS_RANGE_DAYS,
+ OPTIONAL_ANALYTICS_TIMEOUT_MS,
+ PositionAnalytics,
+} from '../../project/gsc.service'
+import { AnalyticsService } from '../analytics.service'
+import { TimeBucketType } from '../dto/getData.dto'
+import {
+ V2SeoBreakdownDto,
+ V2SeoRangeDto,
+ V2SeoSummaryDto,
+ V2SeoTimeseriesDto,
+ V2_SEO_TIME_BUCKETS,
+} from './dto/seo.dto'
+import { V2_DEFAULT_PERIOD, V2BaseQueryDto } from './dto/v2-base.dto'
+import { envelope, V2Envelope } from './mappers/envelope'
+import {
+ bucketSeoDateSeries,
+ mapSeoBreakdownRows,
+ mapSeoSummary,
+ mapSeoTimeseries,
+ SeoDateSeriesEntry,
+ SeoSummaryData,
+} from './mappers/seo.mapper'
+import { toIsoTimestamp, TimeseriesRow } from './mappers/timeseries.mapper'
+import { parseV2Filters, V2Filter } from './query/filters.translator'
+import {
+ getSeoBreakdownDimension,
+ listSeoDimensions,
+ listSeoMetrics,
+ parseSeoMetricsParam,
+ SEO_SORT,
+ toGscFiltersJson,
+ validateSeoFilters,
+} from './registry/seo'
+
+dayjs.extend(utc)
+
+const DEFAULT_SEO_BREAKDOWN_LIMIT = 30
+
+const INTRADAY_PERIODS = ['1h', 'today', 'yesterday', '1d']
+
+interface SeoTimeframe {
+ period: string | null
+ timeBucket: TimeBucketType
+ safeTimezone: string
+ groupFrom: string
+ groupTo: string
+ rangeDays: number
+}
+
+const SKIPPED = Symbol('skipped')
+
+/**
+ * Runs an expensive Search Console rollup under a deadline. A timeout aborts
+ * the in-flight paging and reports the panel as skipped; a genuine upstream
+ * failure still propagates, so a broken panel reads as broken rather than as
+ * "too much data".
+ */
+const resolveOptional = async <T>(
+ load: (signal: AbortSignal) => Promise<T>,
+): Promise<T | typeof SKIPPED> => {
+ const controller = new AbortController()
+ let timeout: ReturnType<typeof setTimeout> | undefined
+
+ const loading = load(controller.signal)
+
+ // Aborting rejects `loading` after the race has already settled on SKIPPED;
+ // this keeps that late rejection from surfacing as an unhandled rejection
+ // without stopping Promise.race from seeing a real, pre-deadline failure.
+ loading.catch(() => {})
+
+ try {
+ return await Promise.race([
+ loading,
+ new Promise<typeof SKIPPED>((resolve) => {
+ timeout = setTimeout(() => {
+ controller.abort()
+ resolve(SKIPPED)
+ }, OPTIONAL_ANALYTICS_TIMEOUT_MS)
+ }),
+ ])
+ } finally {
+ if (timeout) {
+ clearTimeout(timeout)
+ }
+ }
+}
+
+@Injectable()
+export class SeoV2Service {
+ constructor(
+ private readonly gscService: GSCService,
+ private readonly analyticsService: AnalyticsService,
+ ) {}
+
+ /**
+ * Search Console has to be connected and a property linked before any of the
+ * data endpoints can answer. Both are project configuration rather than a bad
+ * request, hence 409 rather than 400.
+ *
+ * Call this only after the request itself has been validated: a malformed
+ * filter is a 422 whether or not the project happens to be connected, and
+ * answering 409 first would send callers debugging their query down the
+ * wrong path.
+ */
+ private async requireContext(pid: string): Promise<GSCContext> {
+ const { connected, property } =
+ await this.gscService.getConnectionState(pid)
+
+ if (!connected) {
+ throw new ConflictException(
+ 'Google Search Console is not connected for this project',
+ )
+ }
+
+ if (!property) {
+ throw new ConflictException(
+ 'No Google Search Console property is linked to this project',
+ )
+ }
+
+ return this.gscService.getGSCContext(pid)
+ }
+
+ private prepareFilters(filters: string | undefined): {
+ appliedFilters: V2Filter[]
+ gscFilters: string | undefined
+ } {
+ const appliedFilters = validateSeoFilters(parseV2Filters(filters))
+
+ if (appliedFilters.length > MAX_FILTERS) {
+ throw new UnprocessableEntityException(
+ `Too many filters; at most ${MAX_FILTERS} may be applied at once`,
+ )
+ }
+
+ for (const filter of appliedFilters) {
+ if (String(filter.value).length > MAX_FILTER_EXPRESSION_LENGTH) {
+ throw new UnprocessableEntityException(
+ `The seo filter on '${filter.dimension}' has a value longer than ${MAX_FILTER_EXPRESSION_LENGTH} characters`,
+ )
+ }
+ }
+
+ // GSCService.parseFilters already understands the v2 filter shape, so the
+ // validated filters are handed straight back to it, mirroring how the
+ // ClickHouse data types translate v2 -> v1 JSON -> getFiltersQuery.
+ return { appliedFilters, gscFilters: toGscFiltersJson(appliedFilters) }
+ }
+
+ private resolveTimeframe(
+ dto: V2BaseQueryDto,
+ requestedBucket?: TimeBucketType,
+ ): SeoTimeframe {
+ const { from, to, timezone } = dto
+ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)
+
+ if (Boolean(from) !== Boolean(to)) {
+ throw new BadRequestException(
+ "The 'from' and 'to' parameters must be provided together",
+ )
+ }
+
+ const hasCustomRange = Boolean(from && to)
+ const period = hasCustomRange
+ ? null
+ : dto.period && dto.period !== 'custom'
+ ? dto.period
+ : V2_DEFAULT_PERIOD
+
+ const timeBucket =
+ requestedBucket ??
+ (period && INTRADAY_PERIODS.includes(period)
+ ? TimeBucketType.HOUR
+ : TimeBucketType.DAY)
+
+ // getGroupFromTo validates the bucket against the range, which neither an
+ // open-ended 'all' nor a caller-chosen custom range can satisfy.
+ const groupTimeBucket =
+ hasCustomRange || period === 'all' ? null : timeBucket
+ const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined
+
+ const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(
+ hasCustomRange ? from : undefined,
+ hasCustomRange ? to : undefined,
+ groupTimeBucket,
+ period ?? undefined,
+ safeTimezone,
+ diff,
+ )
+
+ const rangeDays =
+ Math.abs(
+ dayjs(groupTo)
+ .startOf('day')
+ .diff(dayjs(groupFrom).startOf('day'), 'day'),
+ ) + 1
+
+ return { period, timeBucket, safeTimezone, groupFrom, groupTo, rangeDays }
+ }
+
+ private baseMeta(
+ pid: string,
+ timeframe: SeoTimeframe,
+ appliedFilters: V2Filter[],
+ ): Record<string, unknown> {
+ return {
+ pid,
+ period: timeframe.period,
+ from: toIsoTimestamp(timeframe.groupFrom, timeframe.safeTimezone),
+ to: toIsoTimestamp(timeframe.groupTo, timeframe.safeTimezone),
+ timezone: timeframe.safeTimezone,
+ appliedFilters,
+ }
+ }
+
+ async getStatus(
+ pid: string,
+ ): Promise<V2Envelope<{ connected: boolean; property: string | null }>> {
+ const state = await this.gscService.getConnectionState(pid)
+
+ return envelope(state, { pid })
+ }
+
+ /**
+ * Mirrors AnalyticsV2Service.getDimensions so `?type=seo` answers in the same
+ * shape as every other data type on the discovery endpoint.
+ */
+ getDimensions(): V2Envelope<{
+ dimensions: Record<string, unknown>[]
+ metrics: Record<string, unknown>[]
+ }> {
+ const dimensions = listSeoDimensions().map((dimension) => ({
+ name: dimension.api,
+ description: dimension.description,
+ filterOnly: false,
+ extraFields: [] as string[],
+ }))
+
+ const metrics = listSeoMetrics().map((metric) => ({
+ name: metric.api,
+ description: metric.description,
+ format: metric.format,
+ default: Boolean(metric.isDefault),
+ }))
+
+ return envelope({ dimensions, metrics }, { type: 'seo' })
+ }
+
+ async getSummary(
+ pid: string,
+ dto: V2SeoSummaryDto,
+ ): Promise<V2Envelope<SeoSummaryData>> {
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const timeframe = this.resolveTimeframe(dto)
+ const ctx = await this.requireContext(pid)
+ const { groupFrom, groupTo } = timeframe
+
+ const fromDate = dayjs(groupFrom)
+ const durationMs = dayjs(groupTo).diff(fromDate)
+ const previousTo = fromDate
+ .subtract(1, 'millisecond')
+ .format('YYYY-MM-DD HH:mm:ss')
+ const previousFrom = fromDate
+ .subtract(durationMs, 'millisecond')
+ .format('YYYY-MM-DD HH:mm:ss')
+
+ const [current, previous] = await Promise.all([
+ this.gscService.getSummary(pid, groupFrom, groupTo, gscFilters, ctx),
+ this.gscService
+ .getSummary(pid, previousFrom, previousTo, gscFilters, ctx)
+ .catch(() => null),
+ ])
+
+ return envelope(mapSeoSummary(current, previous), {
+ ...this.baseMeta(pid, timeframe, appliedFilters),
+ metrics: listSeoMetrics().map((metric) => metric.api),
+ })
+ }
+
+ async getTimeseries(
+ pid: string,
+ dto: V2SeoTimeseriesDto,
+ ): Promise<V2Envelope<TimeseriesRow[]>> {
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const metrics = parseSeoMetricsParam(dto.metrics).map(
+ (metric) => metric.api,
+ )
+ const timeframe = this.resolveTimeframe(
+ dto,
+ dto.timeBucket as TimeBucketType | undefined,
+ )
+ const ctx = await this.requireContext(pid)
+
+ // Search Console only serves hourly and daily rows; wider buckets are
+ // rolled up from the daily series rather than requested upstream.
+ const series = (await this.gscService.getDateSeries(
+ pid,
+ timeframe.groupFrom,
+ timeframe.groupTo,
+ timeframe.timeBucket === TimeBucketType.HOUR ? 'hour' : 'day',
+ gscFilters,
+ ctx,
+ )) as SeoDateSeriesEntry[]
+
+ const bucketed = bucketSeoDateSeries(series, timeframe.timeBucket)
+
+ return envelope(
+ mapSeoTimeseries(bucketed, metrics, timeframe.safeTimezone),
+ {
+ ...this.baseMeta(pid, timeframe, appliedFilters),
+ metrics,
+ timeBucket: timeframe.timeBucket,
+ allowedTimeBuckets: [...V2_SEO_TIME_BUCKETS],
+ },
+ )
+ }
+
+ async getBreakdown(
+ pid: string,
+ dto: V2SeoBreakdownDto,
+ ): Promise<V2Envelope<Record<string, unknown>[]>> {
+ const dimension = getSeoBreakdownDimension(dto.dimension)
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const metrics = parseSeoMetricsParam(dto.metrics).map(
+ (metric) => metric.api,
+ )
+ const timeframe = this.resolveTimeframe(dto)
+ const limit = dto.limit ?? DEFAULT_SEO_BREAKDOWN_LIMIT
+ const offset = dto.offset ?? 0
+ const ctx = await this.requireContext(pid)
+ const { groupFrom, groupTo } = timeframe
+
+ const rows = await this.fetchBreakdownRows(
+ dimension.gsc,
+ pid,
+ groupFrom,
+ groupTo,
+ limit,
+ offset,
+ gscFilters,
+ ctx,
+ )
+
+ return envelope(mapSeoBreakdownRows(dimension.gsc, rows, metrics), {
+ ...this.baseMeta(pid, timeframe, appliedFilters),
+ dimension: dimension.api,
+ metrics,
+ limit,
+ offset,
+ sort: SEO_SORT,
+ })
+ }
+
+ private fetchBreakdownRows(
+ dimension: 'query' | 'page' | 'country' | 'device',
+ pid: string,
+ from: string,
+ to: string,
+ limit: number,
+ offset: number,
+ filters: string | undefined,
+ ctx: GSCContext,
+ ) {
+ if (dimension === 'query') {
+ return this.gscService.getKeywords(
+ pid,
+ from,
+ to,
+ limit,
+ offset,
+ filters,
+ undefined,
+ ctx,
+ )
+ }
+
+ if (dimension === 'page') {
+ return this.gscService.getTopPages(
+ pid,
+ from,
+ to,
+ limit,
+ offset,
+ filters,
+ undefined,
+ ctx,
+ )
+ }
+
+ if (dimension === 'country') {
+ return this.gscService.getTopCountries(
+ pid,
+ from,
+ to,
+ limit,
+ offset,
+ filters,
+ ctx,
+ )
+ }
+
+ return this.gscService.getTopDevices(
+ pid,
+ from,
+ to,
+ limit,
+ offset,
+ filters,
+ ctx,
+ )
+ }
+
+ async getBrandedTraffic(
+ pid: string,
+ dto: V2SeoRangeDto,
+ ): Promise<V2Envelope<BrandedTrafficAnalytics | null>> {
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const timeframe = this.resolveTimeframe(dto)
+ const ctx = await this.requireContext(pid)
+ const meta = this.baseMeta(pid, timeframe, appliedFilters)
+
+ if (timeframe.rangeDays > MAX_BRANDED_TRAFFIC_RANGE_DAYS) {
+ return envelope(null, {
+ ...meta,
+ skipped: true,
+ skippedReason: 'range_too_large',
+ maxRangeDays: MAX_BRANDED_TRAFFIC_RANGE_DAYS,
+ })
+ }
+
+ const result = await resolveOptional((signal) =>
+ this.gscService.getBrandedTraffic(
+ pid,
+ timeframe.groupFrom,
+ timeframe.groupTo,
+ gscFilters,
+ ctx,
+ signal,
+ ),
+ )
+
+ if (result === SKIPPED) {
+ return envelope(null, {
+ ...meta,
+ skipped: true,
+ skippedReason: 'timeout',
+ timeoutMs: OPTIONAL_ANALYTICS_TIMEOUT_MS,
+ })
+ }
+
+ return envelope(result, { ...meta, skipped: false })
+ }
+
+ async getPositions(
+ pid: string,
+ dto: V2SeoRangeDto,
+ ): Promise<V2Envelope<PositionAnalytics | null>> {
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const timeframe = this.resolveTimeframe(dto)
+ const ctx = await this.requireContext(pid)
+ const meta = this.baseMeta(pid, timeframe, appliedFilters)
+
+ if (timeframe.rangeDays > MAX_POSITION_ANALYTICS_RANGE_DAYS) {
+ return envelope(null, {
+ ...meta,
+ skipped: true,
+ skippedReason: 'range_too_large',
+ maxRangeDays: MAX_POSITION_ANALYTICS_RANGE_DAYS,
+ })
+ }
+
+ const result = await resolveOptional((signal) =>
+ this.gscService.getPositionAnalytics(
+ pid,
+ timeframe.groupFrom,
+ timeframe.groupTo,
+ gscFilters,
+ ctx,
+ signal,
+ ),
+ )
+
+ if (result === SKIPPED) {
+ return envelope(null, {
+ ...meta,
+ skipped: true,
+ skippedReason: 'timeout',
+ timeoutMs: OPTIONAL_ANALYTICS_TIMEOUT_MS,
+ })
+ }
+
+ return envelope(result, { ...meta, skipped: false })
+ }
+}
diff --git a/backend/apps/cloud/src/project/gsc.service.ts b/backend/apps/cloud/src/project/gsc.service.ts
index 41eff7995..851c2996b 100644
--- a/backend/apps/cloud/src/project/gsc.service.ts
+++ b/backend/apps/cloud/src/project/gsc.service.ts
@@ -39,11 +39,17 @@ const ENCRYPTION_KEY = deriveKey('gsc-token')
const MAX_ROW_LIMIT = 25000
const MAX_BRANDED_PAGES = 10
-const MAX_FILTER_EXPRESSION_LENGTH = 500
-const MAX_FILTERS = 20
-const MAX_BRANDED_TRAFFIC_RANGE_DAYS = 31
-const MAX_POSITION_ANALYTICS_RANGE_DAYS = 31
-const OPTIONAL_ANALYTICS_TIMEOUT_MS = 12000
+export const MAX_FILTER_EXPRESSION_LENGTH = 500
+export const MAX_FILTERS = 20
+export const MAX_BRANDED_TRAFFIC_RANGE_DAYS = 31
+export const MAX_POSITION_ANALYTICS_RANGE_DAYS = 31
+export const OPTIONAL_ANALYTICS_TIMEOUT_MS = 12000
+
+/**
+ * Search Console keeps roughly 16 months of history, so an 'all' period is
+ * resolved against a fixed window rather than the project's first event.
+ */
+export const GSC_ALL_TIME_DAYS = 480
const IMPRESSION_POSITION_BUCKETS = [
{ key: 'pos1To3', label: '1-3' },
@@ -67,13 +73,8 @@ type OrganicPositionSeriesEntry = { date: string } & Record<
OrganicPositionBucketKey,
number
>
-type BrandedTrafficAnalytics = { branded: number; nonBranded: number }
-type SkippedBrandedAnalytics = {
- skipped: true
- branded: null
- nonBranded: null
-}
-type PositionAnalytics = {
+export type BrandedTrafficAnalytics = { branded: number; nonBranded: number }
+export type PositionAnalytics = {
impressionsByPosition: {
key: ImpressionPositionBucketKey
label: string
@@ -82,23 +83,6 @@ type PositionAnalytics = {
}[]
organicPositions: OrganicPositionSeriesEntry[]
}
-type SkippedPositionAnalytics = {
- skipped: true
- impressionsByPosition: null
- organicPositions: null
-}
-
-const SKIPPED_BRANDED_ANALYTICS: SkippedBrandedAnalytics = {
- skipped: true,
- branded: null,
- nonBranded: null,
-}
-
-const SKIPPED_POSITION_ANALYTICS: SkippedPositionAnalytics = {
- skipped: true,
- impressionsByPosition: null,
- organicPositions: null,
-}
const initialImpressionPositionBuckets = (): Record<
ImpressionPositionBucketKey,
@@ -140,32 +124,6 @@ const getOrganicPositionBucketKey = (
return 'pos51Plus'
}
-const resolveOptionalAnalytics = async <T>(
- load: (signal: AbortSignal) => Promise<T>,
- fallback: T,
-): Promise<T> => {
- const controller = new AbortController()
- let timeout: ReturnType<typeof setTimeout> | undefined
-
- try {
- return await Promise.race([
- load(controller.signal),
- new Promise<T>((resolve) => {
- timeout = setTimeout(() => {
- controller.abort()
- resolve(fallback)
- }, OPTIONAL_ANALYTICS_TIMEOUT_MS)
- }),
- ])
- } catch {
- return fallback
- } finally {
- if (timeout) {
- clearTimeout(timeout)
- }
- }
-}
-
type GSCRow = {
keys: string[]
clicks?: number
@@ -174,7 +132,7 @@ type GSCRow = {
position?: number
}
-type GSCContext = {
+export type GSCContext = {
sc: ReturnType<typeof searchconsole>
siteUrl: string
}
@@ -398,6 +356,23 @@ export class GSCService {
return { connected, email: project?.gscAccountEmail || null }
}
+ /**
+ * Whether the project can currently be queried: an account must be connected
+ * and one of its properties linked. Unlike getStatus this needs no account
+ * email, so it is safe to expose to anyone with project read access.
+ */
+ async getConnectionState(
+ pid: string,
+ ): Promise<{ connected: boolean; property: string | null }> {
+ const tokens = await this.getStoredTokens(pid)
+ const connected = !_isEmpty(tokens?.refresh_token || tokens?.access_token)
+
+ return {
+ connected,
+ property: connected ? tokens.property_uri || null : null,
+ }
+ }
+
private async getAuthedClientForPid(pid: string) {
const tokens = await this.getStoredTokens(pid)
if (_isEmpty(tokens)) {
@@ -426,7 +401,7 @@ export class GSCService {
return oauth2Client
}
- private async getGSCContext(pid: string): Promise<GSCContext> {
+ async getGSCContext(pid: string): Promise<GSCContext> {
const tokens = await this.getStoredTokens(pid)
if (_isEmpty(tokens) || _isEmpty(tokens.property_uri)) {
throw new BadRequestException(
@@ -1185,97 +1160,4 @@ export class GSCService {
)
}
}
-
- async getDashboard(
- pid: string,
- from: string,
- to: string,
- timeBucket?: string,
- filtersStr?: string,
- ) {
- const connected = await this.isConnected(pid)
- if (!connected) {
- return { notConnected: true }
- }
-
- const tokens = await this.getStoredTokens(pid)
- if (_isEmpty(tokens.property_uri)) {
- return { notConnected: true, noProperty: true }
- }
-
- let ctx: GSCContext
- try {
- ctx = await this.getGSCContext(pid)
- } catch {
- return { notConnected: true }
- }
-
- const fromDate = dayjs(from)
- const toDate = dayjs(to)
- const durationMs = toDate.diff(fromDate)
- const rangeDays =
- Math.abs(toDate.startOf('day').diff(fromDate.startOf('day'), 'day')) + 1
- const shouldLoadBrandedTraffic = rangeDays <= MAX_BRANDED_TRAFFIC_RANGE_DAYS
- const shouldLoadPositionAnalytics =
- rangeDays <= MAX_POSITION_ANALYTICS_RANGE_DAYS
- const prevTo = fromDate
- .subtract(1, 'millisecond')
- .format('YYYY-MM-DD HH:mm:ss')
- const prevFrom = fromDate
- .subtract(durationMs, 'millisecond')
- .format('YYYY-MM-DD HH:mm:ss')
-
- const [
- summary,
- previousSummary,
- dateSeries,
- topPages,
- topQueries,
- topCountries,
- topDevices,
- brandedTraffic,
- positionAnalytics,
- ] = await Promise.all([
- this.getSummary(pid, from, to, filtersStr, ctx),
- this.getSummary(pid, prevFrom, prevTo, filtersStr, ctx).catch(() => null),
- this.getDateSeries(pid, from, to, timeBucket, filtersStr, ctx),
- this.getTopPages(pid, from, to, 50, 0, filtersStr, undefined, ctx),
- this.getKeywords(pid, from, to, 50, 0, filtersStr, undefined, ctx),
- this.getTopCountries(pid, from, to, 50, 0, filtersStr, ctx),
- this.getTopDevices(pid, from, to, 50, 0, filtersStr, ctx),
- shouldLoadBrandedTraffic
- ? resolveOptionalAnalytics<
- BrandedTrafficAnalytics | SkippedBrandedAnalytics
- >(
- (signal) =>
- this.getBrandedTraffic(pid, from, to, filtersStr, ctx, signal),
- SKIPPED_BRANDED_ANALYTICS,
- )
- : Promise.resolve(SKIPPED_BRANDED_ANALYTICS),
- shouldLoadPositionAnalytics
- ? resolveOptionalAnalytics<
- PositionAnalytics | SkippedPositionAnalytics
- >(
- (signal) =>
- this.getPositionAnalytics(pid, from, to, filtersStr, ctx, signal),
- SKIPPED_POSITION_ANALYTICS,
- )
- : Promise.resolve(SKIPPED_POSITION_ANALYTICS),
- ])
-
- return {
- notConnected: false,
- summary,
- previousSummary,
- dateSeries,
- topPages,
- topQueries,
- topCountries,
- topDevices,
- brandedTraffic,
- positionAnalyticsSkipped: 'skipped' in positionAnalytics,
- impressionsByPosition: positionAnalytics.impressionsByPosition,
- organicPositions: positionAnalytics.organicPositions,
- }
- }
}
diff --git a/backend/apps/community/src/analytics/analytics.controller.ts b/backend/apps/community/src/analytics/analytics.controller.ts
index 9c1f8a5e9..61bc50b40 100644
--- a/backend/apps/community/src/analytics/analytics.controller.ts
+++ b/backend/apps/community/src/analytics/analytics.controller.ts
@@ -42,7 +42,7 @@ import { DEFAULT_TIMEZONE } from '../user/entities/user.entity'
import { AuthenticationGuard } from '../auth/guards/authentication.guard'
import { PageviewsDto } from './dto/pageviews.dto'
import { EventsDto } from './dto/events.dto'
-import { GetDataDto, ChartRenderMode, TimeBucketType } from './dto/getData.dto'
+import { GetDataDto, ChartRenderMode } from './dto/getData.dto'
import { GetFiltersDto } from './dto/get-filters.dto'
import { DataDeletionDto } from './dto/data-deletion.dto'
import { GetVersionFiltersDto } from './dto/get-version-filters.dto'
@@ -79,7 +79,7 @@ import { GetHeartbeatStatsDto } from './dto/get-heartbeat-stats'
import { LiveVisitorsDto } from './dto/live-visitors.dto'
import { NoscriptDto } from './dto/noscript.dto'
import { GetKeywordsDto } from './dto/get-keywords.dto'
-import { GSCService } from '../project/gsc.service'
+import { GSC_ALL_TIME_DAYS, GSCService } from '../project/gsc.service'
import { ExperimentService } from '../experiment/experiment.service'
import { getExperimentVariant } from '../feature-flag/evaluation'
@@ -94,9 +94,6 @@ const BOT_RESPONSE = { message: 'Bot traffic detected, request is ignored' }
const ONLINE_VISITORS_WINDOW_MINUTES = 5 // minutes
-// Maximum range for "all time" GSC queries (~16 months, GSC's data retention)
-const GSC_ALL_TIME_DAYS = 480
-
// Performance object validator: none of the values cannot be bigger than 1000 * 60 * 5 (5 minutes) and are >= 0
const MAX_PERFORMANCE_VALUE = 1000 * 60 * 5
const isPerformanceValid = (perf: any) => {
@@ -2864,133 +2861,4 @@ export class AnalyticsController {
const keywords = await this.gscService.getKeywords(pid, groupFrom, groupTo)
return { keywords }
}
-
- @Get('gsc-dashboard')
- @Auth(true, true)
- async getGSCDashboard(
- @Query() data: GetKeywordsDto,
- @CurrentUserId() uid: string,
- @Headers() headers: { 'x-password'?: string },
- ) {
- const {
- pid,
- period,
- from,
- to,
- timezone = DEFAULT_TIMEZONE,
- timeBucket,
- filters,
- } = data
-
- await this.analyticsService.checkProjectAccess(
- pid,
- uid,
- headers['x-password'],
- )
-
- const defaultTimeBucket = ['1h', 'today', 'yesterday', '1d'].includes(
- period,
- )
- ? TimeBucketType.HOUR
- : TimeBucketType.DAY
- const finalTimeBucket = (timeBucket || defaultTimeBucket) as TimeBucketType
- let groupTimeBucket: TimeBucketType | null = finalTimeBucket
- if (period === 'all' || period === 'custom') {
- groupTimeBucket = null
- }
-
- this.logger.log(
- `pid: ${pid}, period: ${period}, timeBucket: ${finalTimeBucket}, filters: ${filters}`,
- 'GET /analytics/gsc-dashboard',
- )
-
- const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined
-
- const safeTimezone = this.analyticsService.getSafeTimezone(timezone)
- const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(
- from,
- to,
- groupTimeBucket,
- period,
- safeTimezone,
- diff,
- )
-
- return this.gscService.getDashboard(
- pid,
- groupFrom,
- groupTo,
- finalTimeBucket,
- filters,
- )
- }
-
- @Get('gsc-details')
- @Auth(true, true)
- async getGSCDetails(
- @Query() data: GetKeywordsDto,
- @CurrentUserId() uid: string,
- @Headers() headers: { 'x-password'?: string },
- ) {
- const {
- pid,
- period,
- from,
- to,
- timezone = DEFAULT_TIMEZONE,
- page,
- query,
- } = data
-
- this.logger.log(
- `pid: ${pid}, period: ${period}, page: ${page}, query: ${query}`,
- 'GET /analytics/gsc-details',
- )
-
- await this.analyticsService.checkProjectAccess(
- pid,
- uid,
- headers['x-password'],
- )
-
- const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined
-
- const safeTimezone = this.analyticsService.getSafeTimezone(timezone)
- const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(
- from,
- to,
- null,
- period,
- safeTimezone,
- diff,
- )
-
- if (page) {
- const keywords = await this.gscService.getKeywords(
- pid,
- groupFrom,
- groupTo,
- 50,
- 0,
- undefined,
- page,
- )
- return { type: 'queries', data: keywords }
- }
-
- if (query) {
- const pages = await this.gscService.getTopPages(
- pid,
- groupFrom,
- groupTo,
- 50,
- 0,
- undefined,
- query,
- )
- return { type: 'pages', data: pages }
- }
-
- return { type: 'none', data: [] }
- }
}
diff --git a/backend/apps/community/src/analytics/analytics.module.ts b/backend/apps/community/src/analytics/analytics.module.ts
index da9d6ce47..413e1b5df 100644
--- a/backend/apps/community/src/analytics/analytics.module.ts
+++ b/backend/apps/community/src/analytics/analytics.module.ts
@@ -11,6 +11,7 @@ import { AppLoggerModule } from '../logger/logger.module'
import { ProjectModule } from '../project/project.module'
import { ExperimentModule } from '../experiment/experiment.module'
import { AnalyticsV2Service } from './v2/analytics-v2.service'
+import { SeoV2Service } from './v2/seo-v2.service'
import { TrafficV2Controller } from './v2/controllers/traffic-v2.controller'
import { PerformanceV2Controller } from './v2/controllers/performance-v2.controller'
import { CaptchaV2Controller } from './v2/controllers/captcha-v2.controller'
@@ -18,12 +19,14 @@ import { ErrorsV2Controller } from './v2/controllers/errors-v2.controller'
import { SessionsV2Controller } from './v2/controllers/sessions-v2.controller'
import { ProfilesV2Controller } from './v2/controllers/profiles-v2.controller'
import { ProjectV2Controller } from './v2/controllers/project-v2.controller'
+import { SeoV2Controller } from './v2/controllers/seo-v2.controller'
@Module({
imports: [AppLoggerModule, ProjectModule, forwardRef(() => ExperimentModule)],
providers: [
AnalyticsService,
AnalyticsV2Service,
+ SeoV2Service,
BotDetectionService,
SaltService,
HeartbeatGateway,
@@ -40,6 +43,7 @@ import { ProjectV2Controller } from './v2/controllers/project-v2.controller'
SessionsV2Controller,
ProfilesV2Controller,
ProjectV2Controller,
+ SeoV2Controller,
],
})
export class AnalyticsModule {}
diff --git a/backend/apps/community/src/analytics/protection/public-project-cache.interceptor.ts b/backend/apps/community/src/analytics/protection/public-project-cache.interceptor.ts
index 57ee4c8cf..431b281e7 100644
--- a/backend/apps/community/src/analytics/protection/public-project-cache.interceptor.ts
+++ b/backend/apps/community/src/analytics/protection/public-project-cache.interceptor.ts
@@ -33,8 +33,6 @@ const CACHEABLE_ROUTES = new Set([
'funnel-sessions',
'custom-events',
'keywords',
- 'gsc-dashboard',
- 'gsc-details',
])
@Injectable()
diff --git a/backend/apps/community/src/analytics/v2/__tests__/seo.mapper.spec.ts b/backend/apps/community/src/analytics/v2/__tests__/seo.mapper.spec.ts
new file mode 100644
index 000000000..d90e11b99
--- /dev/null
+++ b/backend/apps/community/src/analytics/v2/__tests__/seo.mapper.spec.ts
@@ -0,0 +1,210 @@
+import { TimeBucketType } from '../../dto/getData.dto'
+import {
+ bucketSeoDateSeries,
+ gscCountryToAlpha2,
+ mapSeoBreakdownRows,
+ mapSeoSummary,
+ mapSeoTimeseries,
+ SeoDateSeriesEntry,
+} from '../mappers/seo.mapper'
+
+const day = (
+ date: string,
+ clicks: number,
+ impressions: number,
+ position: number,
+): SeoDateSeriesEntry => ({
+ date,
+ clicks,
+ impressions,
+ position,
+ ctr: impressions > 0 ? (clicks / impressions) * 100 : 0,
+})
+
+describe('gscCountryToAlpha2', () => {
+ it('converts Search Console alpha-3 to the alpha-2 the rest of v2 uses', () => {
+ expect(gscCountryToAlpha2('usa')).toBe('US')
+ expect(gscCountryToAlpha2('deu')).toBe('DE')
+ expect(gscCountryToAlpha2('ukr')).toBe('UA')
+ })
+
+ it('passes through anything it cannot map rather than dropping the row', () => {
+ expect(gscCountryToAlpha2('zzz')).toBe('ZZZ')
+ expect(gscCountryToAlpha2('')).toBe('')
+ })
+})
+
+describe('mapSeoBreakdownRows', () => {
+ it("reads getKeywords' `count` as clicks", () => {
+ expect(
+ mapSeoBreakdownRows(
+ 'query',
+ [
+ {
+ name: 'swetrix',
+ count: 12,
+ impressions: 400,
+ ctr: 3,
+ position: 4.2,
+ },
+ ],
+ ['clicks', 'impressions', 'ctr', 'position'],
+ ),
+ ).toEqual([
+ { value: 'swetrix', clicks: 12, impressions: 400, ctr: 3, position: 4.2 },
+ ])
+ })
+
+ it('reads the label field each per-dimension getter returns', () => {
+ expect(
+ mapSeoBreakdownRows('page', [{ page: '/blog', clicks: 5 }], ['clicks']),
+ ).toEqual([{ value: '/blog', clicks: 5 }])
+
+ expect(
+ mapSeoBreakdownRows(
+ 'device',
+ [{ device: 'mobile', clicks: 3 }],
+ ['clicks'],
+ ),
+ ).toEqual([{ value: 'mobile', clicks: 3 }])
+ })
+
+ it('normalises country rows to alpha-2', () => {
+ expect(
+ mapSeoBreakdownRows(
+ 'country',
+ [{ country: 'usa', clicks: 9 }],
+ ['clicks'],
+ ),
+ ).toEqual([{ value: 'US', clicks: 9 }])
+ })
+
+ it('only emits the requested metrics', () => {
+ expect(
+ mapSeoBreakdownRows(
+ 'query',
+ [{ name: 'a', count: 1, impressions: 2, ctr: 50, position: 1 }],
+ ['clicks'],
+ ),
+ ).toEqual([{ value: 'a', clicks: 1 }])
+ })
+
+ it('defaults missing values to zero rather than emitting NaN', () => {
+ expect(
+ mapSeoBreakdownRows('query', [{ name: 'a' }], ['clicks', 'position']),
+ ).toEqual([{ value: 'a', clicks: 0, position: 0 }])
+ })
+})
+
+describe('mapSeoSummary', () => {
+ it('reports the absolute change between periods, matching the other v2 summaries', () => {
+ expect(
+ mapSeoSummary(
+ { clicks: 120, impressions: 3000, ctr: 4, position: 8.1 },
+ { clicks: 100, impressions: 2500, ctr: 4.5, position: 9.4 },
+ ),
+ ).toEqual({
+ current: { clicks: 120, impressions: 3000, ctr: 4, position: 8.1 },
+ previous: { clicks: 100, impressions: 2500, ctr: 4.5, position: 9.4 },
+ change: { clicks: 20, impressions: 500, ctr: -0.5, position: -1.3 },
+ })
+ })
+
+ it('treats a missing previous period as zeroes', () => {
+ const summary = mapSeoSummary(
+ { clicks: 10, impressions: 100, ctr: 10, position: 2 },
+ null,
+ )
+
+ expect(summary.previous).toEqual({
+ clicks: 0,
+ impressions: 0,
+ ctr: 0,
+ position: 0,
+ })
+ expect(summary.change.clicks).toBe(10)
+ })
+})
+
+describe('bucketSeoDateSeries', () => {
+ const series = [
+ day('2026-01-05', 10, 100, 10),
+ day('2026-01-20', 30, 300, 2),
+ day('2026-02-10', 5, 50, 4),
+ ]
+
+ it('leaves the native hour and day granularity untouched', () => {
+ expect(bucketSeoDateSeries(series, TimeBucketType.DAY)).toBe(series)
+ expect(bucketSeoDateSeries(series, TimeBucketType.HOUR)).toBe(series)
+ })
+
+ it('sums clicks and impressions into month buckets', () => {
+ const [january, february] = bucketSeoDateSeries(
+ series,
+ TimeBucketType.MONTH,
+ )
+
+ expect(january.date).toBe('2026-01-01')
+ expect(january.clicks).toBe(40)
+ expect(january.impressions).toBe(400)
+ expect(february.date).toBe('2026-02-01')
+ expect(february.clicks).toBe(5)
+ })
+
+ it('recomputes ctr from the bucket totals rather than averaging it', () => {
+ const [january] = bucketSeoDateSeries(series, TimeBucketType.MONTH)
+ // 40 clicks / 400 impressions, not the mean of the two daily CTRs.
+ expect(january.ctr).toBe(10)
+ })
+
+ it('averages position weighted by impressions', () => {
+ const [january] = bucketSeoDateSeries(series, TimeBucketType.MONTH)
+ // (10*100 + 2*300) / 400 = 4, whereas a plain mean would give 6.
+ expect(january.position).toBe(4)
+ })
+
+ it('rolls a whole year up into one bucket', () => {
+ const yearly = bucketSeoDateSeries(series, TimeBucketType.YEAR)
+
+ expect(yearly).toHaveLength(1)
+ expect(yearly[0].date).toBe('2026-01-01')
+ expect(yearly[0].clicks).toBe(45)
+ })
+
+ it('reports zeroed rates for a bucket with no impressions', () => {
+ const [bucket] = bucketSeoDateSeries(
+ [day('2026-01-05', 0, 0, 0)],
+ TimeBucketType.MONTH,
+ )
+
+ expect(bucket.ctr).toBe(0)
+ expect(bucket.position).toBe(0)
+ })
+})
+
+describe('mapSeoTimeseries', () => {
+ it('emits ISO timestamps in the requested timezone', () => {
+ const [row] = mapSeoTimeseries(
+ [day('2026-01-05', 10, 100, 3)],
+ ['clicks'],
+ 'Europe/Kyiv',
+ )
+
+ expect(row.timestamp).toBe('2026-01-05T00:00:00+02:00')
+ expect(row.clicks).toBe(10)
+ })
+
+ it('only emits the requested metrics', () => {
+ const [row] = mapSeoTimeseries(
+ [day('2026-01-05', 10, 100, 3)],
+ ['clicks', 'position'],
+ 'UTC',
+ )
+
+ expect(Object.keys(row).sort()).toEqual(['clicks', 'position', 'timestamp'])
+ })
+
+ it('drops rows Search Console returned without a date', () => {
+ expect(mapSeoTimeseries([day('', 1, 1, 1)], ['clicks'], 'UTC')).toEqual([])
+ })
+})
diff --git a/backend/apps/community/src/analytics/v2/__tests__/seo.registry.spec.ts b/backend/apps/community/src/analytics/v2/__tests__/seo.registry.spec.ts
new file mode 100644
index 000000000..145d9407b
--- /dev/null
+++ b/backend/apps/community/src/analytics/v2/__tests__/seo.registry.spec.ts
@@ -0,0 +1,134 @@
+import { UnprocessableEntityException } from '@nestjs/common'
+
+import { V2Filter } from '../query/filters.translator'
+import {
+ getDefaultSeoMetrics,
+ getSeoBreakdownDimension,
+ getSeoMetric,
+ listSeoDimensions,
+ parseSeoMetricsParam,
+ toGscFiltersJson,
+ validateSeoFilters,
+ V2_SEO_DIMENSIONS,
+} from '../registry/seo'
+
+const filter = (overrides: Partial<V2Filter> = {}): V2Filter =>
+ ({
+ dimension: 'country',
+ operator: 'is',
+ value: 'US',
+ ...overrides,
+ }) as V2Filter
+
+describe('seo dimension lookups', () => {
+ it('resolves every declared dimension to its Search Console name', () => {
+ expect(getSeoBreakdownDimension('query').gsc).toBe('query')
+ expect(getSeoBreakdownDimension('page').gsc).toBe('page')
+ expect(getSeoBreakdownDimension('country').gsc).toBe('country')
+ expect(getSeoBreakdownDimension('device').gsc).toBe('device')
+ })
+
+ it('rejects unknown dimensions with 422', () => {
+ expect(() => getSeoBreakdownDimension('nope')).toThrow(
+ UnprocessableEntityException,
+ )
+ // Valid for traffic, but Search Console reports nothing like it.
+ expect(() => getSeoBreakdownDimension('browser')).toThrow(
+ UnprocessableEntityException,
+ )
+ })
+
+ it('has unique api names', () => {
+ const names = listSeoDimensions().map((dimension) => dimension.api)
+ expect(new Set(names).size).toBe(names.length)
+ })
+
+ it('only maps onto dimensions Search Console actually serves', () => {
+ for (const dimension of V2_SEO_DIMENSIONS) {
+ expect(['query', 'page', 'country', 'device']).toContain(dimension.gsc)
+ }
+ })
+})
+
+describe('seo metric lookups', () => {
+ it('resolves metrics and rejects unknown ones', () => {
+ expect(getSeoMetric('clicks').api).toBe('clicks')
+ expect(() => getSeoMetric('visitors')).toThrow(UnprocessableEntityException)
+ })
+
+ it('returns all four metrics by default', () => {
+ expect(getDefaultSeoMetrics().map((metric) => metric.api)).toEqual([
+ 'clicks',
+ 'impressions',
+ 'ctr',
+ 'position',
+ ])
+ })
+
+ it('parses and dedupes the metrics CSV param', () => {
+ expect(
+ parseSeoMetricsParam('clicks, impressions,clicks').map(
+ (metric) => metric.api,
+ ),
+ ).toEqual(['clicks', 'impressions'])
+
+ expect(parseSeoMetricsParam(undefined).map((metric) => metric.api)).toEqual(
+ ['clicks', 'impressions', 'ctr', 'position'],
+ )
+
+ expect(() => parseSeoMetricsParam('bogus')).toThrow(
+ UnprocessableEntityException,
+ )
+ })
+})
+
+describe('validateSeoFilters', () => {
+ it('accepts scalar filters on known dimensions', () => {
+ const filters = [filter(), filter({ dimension: 'query', value: 'swetrix' })]
+ expect(validateSeoFilters(filters)).toBe(filters)
+ })
+
+ it('rejects filters on dimensions Search Console cannot filter by', () => {
+ expect(() =>
+ validateSeoFilters([filter({ dimension: 'browser' })]),
+ ).toThrow(UnprocessableEntityException)
+ })
+
+ it('rejects array values, which have no dimensionFilterGroups equivalent', () => {
+ expect(() => validateSeoFilters([filter({ value: ['US', 'DE'] })])).toThrow(
+ UnprocessableEntityException,
+ )
+ })
+
+ it('rejects null values, since Search Console reports no unset values', () => {
+ expect(() => validateSeoFilters([filter({ value: null })])).toThrow(
+ UnprocessableEntityException,
+ )
+ })
+})
+
+describe('toGscFiltersJson', () => {
+ it('renames query -> keywords, the key GSCService.parseFilters expects', () => {
+ const json = toGscFiltersJson([
+ filter({ dimension: 'query', value: 'swetrix' }),
+ ])
+
+ expect(JSON.parse(json)).toEqual([
+ { dimension: 'keywords', operator: 'is', value: 'swetrix' },
+ ])
+ })
+
+ it('leaves dimensions that already share a name alone', () => {
+ const json = toGscFiltersJson([
+ filter({ dimension: 'page', operator: 'contains', value: '/blog' }),
+ ])
+
+ expect(JSON.parse(json)).toEqual([
+ { dimension: 'page', operator: 'contains', value: '/blog' },
+ ])
+ })
+
+ it('returns undefined for no filters so no filter group is sent', () => {
+ expect(toGscFiltersJson([])).toBeUndefined()
+ })
+})
diff --git a/backend/apps/community/src/analytics/v2/controllers/project-v2.controller.ts b/backend/apps/community/src/analytics/v2/controllers/project-v2.controller.ts
index 48df6c494..bb3a81ff2 100644
--- a/backend/apps/community/src/analytics/v2/controllers/project-v2.controller.ts
+++ b/backend/apps/community/src/analytics/v2/controllers/project-v2.controller.ts
@@ -33,6 +33,7 @@ import {
V2FunnelSessionsQueryDto,
} from '../dto/project.dto'
import { V2ProjectParamsDto } from '../dto/v2-base.dto'
+import { SeoV2Service } from '../seo-v2.service'
@ApiTags('Analytics v2')
@ApiBearerAuth()
@@ -44,6 +45,7 @@ import { V2ProjectParamsDto } from '../dto/v2-base.dto'
export class ProjectV2Controller {
constructor(
private readonly analyticsV2Service: AnalyticsV2Service,
+ private readonly seoV2Service: SeoV2Service,
private readonly logger: AppLoggerService,
) {}
@@ -144,6 +146,12 @@ export class ProjectV2Controller {
headers['x-password'],
)
+ // SEO is served by the Search Console API rather than ClickHouse, so it
+ // keeps its own registry outside the sqlExpr-based one.
+ if (query.type === 'seo') {
+ return this.seoV2Service.getDimensions()
+ }
+
return this.analyticsV2Service.getDimensions(query.type || 'traffic')
}
diff --git a/backend/apps/community/src/analytics/v2/controllers/seo-v2.controller.ts b/backend/apps/community/src/analytics/v2/controllers/seo-v2.controller.ts
new file mode 100644
index 000000000..85ee82f0c
--- /dev/null
+++ b/backend/apps/community/src/analytics/v2/controllers/seo-v2.controller.ts
@@ -0,0 +1,202 @@
+import {
+ Controller,
+ Get,
+ Headers,
+ Param,
+ Query,
+ UseGuards,
+ UseInterceptors,
+ UsePipes,
+ ValidationPipe,
+} from '@nestjs/common'
+import {
+ ApiBearerAuth,
+ ApiOperation,
+ ApiSecurity,
+ ApiTags,
+} from '@nestjs/swagger'
+
+import { Auth } from '../../../auth/decorators'
+import { CurrentUserId } from '../../../auth/decorators/current-user-id.decorator'
+import { OptionalJwtAccessTokenGuard } from '../../../auth/guards'
+import { AuthenticationGuard } from '../../../auth/guards/authentication.guard'
+import { AppLoggerService } from '../../../logger/logger.service'
+import { AnalyticsReadGuard } from '../../protection/analytics-read.guard'
+import { CacheableAnalytics } from '../../protection/cacheable-analytics.decorator'
+import { PublicProjectCacheInterceptor } from '../../protection/public-project-cache.interceptor'
+import { AnalyticsV2Service } from '../analytics-v2.service'
+import {
+ V2SeoBreakdownDto,
+ V2SeoRangeDto,
+ V2SeoSummaryDto,
+ V2SeoTimeseriesDto,
+} from '../dto/seo.dto'
+import { V2ProjectParamsDto } from '../dto/v2-base.dto'
+import { SeoV2Service } from '../seo-v2.service'
+
+@ApiTags('Analytics v2')
+@ApiBearerAuth()
+@ApiSecurity('apiKey')
+@UseGuards(OptionalJwtAccessTokenGuard, AuthenticationGuard, AnalyticsReadGuard)
+@UseInterceptors(PublicProjectCacheInterceptor)
+@UsePipes(new ValidationPipe({ transform: true }))
+@Controller('v2/projects/:pid/seo')
+export class SeoV2Controller {
+ constructor(
+ private readonly seoV2Service: SeoV2Service,
+ private readonly analyticsV2Service: AnalyticsV2Service,
+ private readonly logger: AppLoggerService,
+ ) {}
+
+ @Get('status')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'Search Console connection status',
+ description:
+ 'Whether Google Search Console is connected for this project and which property is linked. The other seo endpoints return 409 until both are true.',
+ })
+ async getStatus(
+ @Param() { pid }: V2ProjectParamsDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/status')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getStatus(pid)
+ }
+
+ @Get('summary')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'SEO summary',
+ description:
+ 'Clicks, impressions, CTR and average position for the selected period, the previous period of the same length, and the change between them.',
+ })
+ async getSummary(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoSummaryDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/summary')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getSummary(pid, query)
+ }
+
+ @Get('timeseries')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'SEO timeseries',
+ description:
+ 'Selected SEO metrics grouped by time bucket, as rows of objects with ISO-8601 timestamps.',
+ })
+ async getTimeseries(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoTimeseriesDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/timeseries')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getTimeseries(pid, query)
+ }
+
+ @Get('breakdown')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'SEO breakdown',
+ description:
+ 'SEO metrics grouped by a single dimension (query, page, country, device), paginated. Rows are always ordered by clicks descending.',
+ })
+ async getBreakdown(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoBreakdownDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(
+ `pid: ${pid}, dimension: ${query.dimension}`,
+ 'GET /v2/projects/:pid/seo/breakdown',
+ )
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getBreakdown(pid, query)
+ }
+
+ @Get('branded-traffic')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'Branded vs non-branded traffic',
+ description:
+ "Clicks split by whether the search query contained one of the project's brand keywords. Skipped for ranges wider than 31 days.",
+ })
+ async getBrandedTraffic(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoRangeDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/branded-traffic')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getBrandedTraffic(pid, query)
+ }
+
+ @Get('positions')
+ @Auth(true, true)
+ @CacheableAnalytics()
+ @ApiOperation({
+ summary: 'Search position analytics',
+ description:
+ 'Impressions bucketed by search position, and the daily count of ranking queries per position bucket. Skipped for ranges wider than 31 days.',
+ })
+ async getPositions(
+ @Param() { pid }: V2ProjectParamsDto,
+ @Query() query: V2SeoRangeDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ this.logger.log(`pid: ${pid}`, 'GET /v2/projects/:pid/seo/positions')
+
+ await this.analyticsV2Service.assertReadAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.seoV2Service.getPositions(pid, query)
+ }
+}
diff --git a/backend/apps/community/src/analytics/v2/dto/project.dto.ts b/backend/apps/community/src/analytics/v2/dto/project.dto.ts
index 44dddc3a9..e3cbc8dc5 100644
--- a/backend/apps/community/src/analytics/v2/dto/project.dto.ts
+++ b/backend/apps/community/src/analytics/v2/dto/project.dto.ts
@@ -77,15 +77,15 @@ export class V2FunnelSessionsQueryDto extends V2FunnelQueryDto {
export class V2DimensionsQueryDto {
@ApiProperty({
required: false,
- enum: ['traffic', 'performance', 'captcha', 'errors'],
+ enum: ['traffic', 'performance', 'captcha', 'errors', 'seo'],
default: 'traffic',
description: 'Data type to list dimensions and metrics for',
})
@IsOptional()
- @IsIn(['traffic', 'performance', 'captcha', 'errors'], {
+ @IsIn(['traffic', 'performance', 'captcha', 'errors', 'seo'], {
message: 'The provided type is incorrect',
})
- type?: 'traffic' | 'performance' | 'captcha' | 'errors'
+ type?: 'traffic' | 'performance' | 'captcha' | 'errors' | 'seo'
}
export class V2DimensionValuesParamsDto extends V2ProjectParamsDto {
diff --git a/backend/apps/community/src/analytics/v2/dto/seo.dto.ts b/backend/apps/community/src/analytics/v2/dto/seo.dto.ts
new file mode 100644
index 000000000..f8153b33a
--- /dev/null
+++ b/backend/apps/community/src/analytics/v2/dto/seo.dto.ts
@@ -0,0 +1,115 @@
+import { ApiProperty } from '@nestjs/swagger'
+import { Type } from 'class-transformer'
+import {
+ IsIn,
+ IsInt,
+ IsNotEmpty,
+ IsOptional,
+ IsString,
+ Max,
+ Min,
+} from 'class-validator'
+
+import { TimeBucketType } from '../../dto/getData.dto'
+import { SEO_SORT } from '../registry/seo'
+import { V2BaseQueryDto } from './v2-base.dto'
+
+const V2_SEO_MAX_BREAKDOWN_LIMIT = 100
+
+/**
+ * Search Console reports nothing below hourly granularity, so `minute` is
+ * excluded from the buckets a caller may ask for.
+ */
+export const V2_SEO_TIME_BUCKETS = [
+ TimeBucketType.HOUR,
+ TimeBucketType.DAY,
+ TimeBucketType.MONTH,
+ TimeBucketType.YEAR,
+] as const
+
+export type V2SeoTimeBucket = (typeof V2_SEO_TIME_BUCKETS)[number]
+
+export class V2SeoSummaryDto extends V2BaseQueryDto {}
+
+export class V2SeoRangeDto extends V2BaseQueryDto {}
+
+export class V2SeoTimeseriesDto extends V2BaseQueryDto {
+ @ApiProperty({
+ required: false,
+ enum: V2_SEO_TIME_BUCKETS,
+ description:
+ "Time bucket for grouping. One of: hour, day, month, year. Defaults to 'day', or 'hour' for intraday periods.",
+ })
+ @IsOptional()
+ @IsIn(V2_SEO_TIME_BUCKETS as readonly string[], {
+ message: `The provided timeBucket is incorrect. Search Console supports: ${V2_SEO_TIME_BUCKETS.join(', ')}`,
+ })
+ timeBucket?: V2SeoTimeBucket
+
+ @ApiProperty({
+ required: false,
+ description:
+ 'Comma-separated metric names to return. Defaults to clicks, impressions, ctr and position.',
+ example: 'clicks,impressions',
+ })
+ @IsOptional()
+ @IsString()
+ metrics?: string
+}
+
+export class V2SeoBreakdownDto extends V2BaseQueryDto {
+ @ApiProperty({
+ description:
+ 'Dimension to break down by. One of: query, page, country, device',
+ example: 'query',
+ })
+ @IsNotEmpty()
+ @IsString()
+ dimension: string
+
+ @ApiProperty({
+ required: false,
+ description:
+ 'Comma-separated metric names to compute per dimension value. Defaults to clicks, impressions, ctr and position.',
+ example: 'clicks,impressions',
+ })
+ @IsOptional()
+ @IsString()
+ metrics?: string
+
+ @ApiProperty({
+ required: false,
+ default: 30,
+ maximum: V2_SEO_MAX_BREAKDOWN_LIMIT,
+ description: 'Number of rows to return',
+ })
+ @IsOptional()
+ @Type(() => Number)
+ @IsInt()
+ @Min(1)
+ @Max(V2_SEO_MAX_BREAKDOWN_LIMIT)
+ limit?: number
+
+ @ApiProperty({
+ required: false,
+ default: 0,
+ description: 'Number of rows to skip (pagination)',
+ })
+ @IsOptional()
+ @Type(() => Number)
+ @IsInt()
+ @Min(0)
+ offset?: number
+
+ @ApiProperty({
+ required: false,
+ enum: [SEO_SORT],
+ default: SEO_SORT,
+ description: `Search Console orders rows by clicks descending and offers no sort control, so '${SEO_SORT}' is the only accepted value.`,
+ })
+ @IsOptional()
+ @IsIn([SEO_SORT], {
+ message: `Search Console always orders rows by clicks descending; omit 'sort' or pass '${SEO_SORT}'`,
+ })
+ sort?: string
+}
diff --git a/backend/apps/community/src/analytics/v2/mappers/seo.mapper.ts b/backend/apps/community/src/analytics/v2/mappers/seo.mapper.ts
new file mode 100644
index 000000000..efd1ab46c
--- /dev/null
+++ b/backend/apps/community/src/analytics/v2/mappers/seo.mapper.ts
@@ -0,0 +1,221 @@
+import countries from 'i18n-iso-countries'
+import dayjs from 'dayjs'
+
+import { TimeBucketType } from '../../dto/getData.dto'
+import { V2SeoGscDimension } from '../registry/seo'
+import { toIsoTimestamp, TimeseriesRow } from './timeseries.mapper'
+
+export interface SeoMetricValues {
+ clicks: number
+ impressions: number
+ ctr: number
+ position: number
+}
+
+export type SeoDateSeriesEntry = { date: string } & SeoMetricValues
+
+export interface SeoSummaryData {
+ current: SeoMetricValues
+ previous: SeoMetricValues
+ change: SeoMetricValues
+}
+
+const round = (value: unknown, precision: number): number => {
+ const number = Number(value)
+
+ if (!Number.isFinite(number)) {
+ return 0
+ }
+
+ const factor = 10 ** precision
+
+ return Math.round(number * factor) / factor
+}
+
+const toInteger = (value: unknown): number => Math.round(Number(value) || 0)
+
+/**
+ * Search Console reports countries as lowercase ISO 3166-1 alpha-3, while the
+ * rest of the v2 surface (and the `cc` column behind the traffic `country`
+ * dimension) uses uppercase alpha-2. Normalise so a `country` value means the
+ * same thing whichever data type produced it.
+ */
+export const gscCountryToAlpha2 = (country: string): string => {
+ const alpha2 = countries.alpha3ToAlpha2(String(country || '').toUpperCase())
+
+ return alpha2 || String(country || '').toUpperCase()
+}
+
+const EMPTY_METRICS: SeoMetricValues = {
+ clicks: 0,
+ impressions: 0,
+ ctr: 0,
+ position: 0,
+}
+
+const mapSeoMetricValues = (
+ values: Partial<SeoMetricValues> | null | undefined,
+): SeoMetricValues => ({
+ clicks: toInteger(values?.clicks),
+ impressions: toInteger(values?.impressions),
+ ctr: round(values?.ctr, 2),
+ position: round(values?.position, 2),
+})
+
+export const mapSeoSummary = (
+ current: Partial<SeoMetricValues> | null | undefined,
+ previous: Partial<SeoMetricValues> | null | undefined,
+): SeoSummaryData => {
+ const mappedCurrent = mapSeoMetricValues(current)
+ const mappedPrevious = previous ? mapSeoMetricValues(previous) : EMPTY_METRICS
+
+ return {
+ current: mappedCurrent,
+ previous: mappedPrevious,
+ change: {
+ clicks: mappedCurrent.clicks - mappedPrevious.clicks,
+ impressions: mappedCurrent.impressions - mappedPrevious.impressions,
+ ctr: round(mappedCurrent.ctr - mappedPrevious.ctr, 2),
+ position: round(mappedCurrent.position - mappedPrevious.position, 2),
+ },
+ }
+}
+
+/**
+ * A raw row as returned by one of the GSCService per-dimension getters. They
+ * disagree on the label field, and getKeywords calls its click count `count`.
+ */
+export interface GscBreakdownRow extends Partial<SeoMetricValues> {
+ name?: string
+ page?: string
+ country?: string
+ device?: string
+ count?: number
+}
+
+const readRowValue = (
+ dimension: V2SeoGscDimension,
+ row: GscBreakdownRow,
+): string => {
+ if (dimension === 'query') return row.name ?? ''
+ if (dimension === 'page') return row.page ?? ''
+ if (dimension === 'country') return gscCountryToAlpha2(row.country ?? '')
+
+ return row.device ?? ''
+}
+
+export const mapSeoBreakdownRows = (
+ dimension: V2SeoGscDimension,
+ rows: GscBreakdownRow[],
+ metrics: string[],
+): Record<string, unknown>[] =>
+ rows.map((row) => {
+ const values = mapSeoMetricValues({
+ clicks: row.clicks ?? row.count,
+ impressions: row.impressions,
+ ctr: row.ctr,
+ position: row.position,
+ })
+
+ const mapped: Record<string, unknown> = {
+ value: readRowValue(dimension, row),
+ }
+
+ for (const metric of metrics) {
+ mapped[metric] = values[metric as keyof SeoMetricValues]
+ }
+
+ return mapped
+ })
+
+const startOfBucket = (date: string, bucket: TimeBucketType): string => {
+ const parsed = dayjs(date)
+
+ if (bucket === TimeBucketType.MONTH) {
+ return parsed.startOf('month').format('YYYY-MM-DD')
+ }
+
+ if (bucket === TimeBucketType.YEAR) {
+ return parsed.startOf('year').format('YYYY-MM-DD')
+ }
+
+ return date
+}
+
+/**
+ * Search Console only serves hourly and daily rows, so wider buckets are rolled
+ * up here. Clicks and impressions sum; ctr is recomputed from the totals and
+ * position is averaged weighted by impressions, since neither is additive.
+ */
+export const bucketSeoDateSeries = (
+ series: SeoDateSeriesEntry[],
+ bucket: TimeBucketType,
+): SeoDateSeriesEntry[] => {
+ if (bucket !== TimeBucketType.MONTH && bucket !== TimeBucketType.YEAR) {
+ return series
+ }
+
+ const buckets = new Map<
+ string,
+ { clicks: number; impressions: number; weightedPosition: number }
+ >()
+ const orderedKeys: string[] = []
+
+ for (const entry of series) {
+ if (!entry.date) continue
+
+ const key = startOfBucket(entry.date, bucket)
+ const existing = buckets.get(key)
+
+ if (existing) {
+ existing.clicks += entry.clicks
+ existing.impressions += entry.impressions
+ existing.weightedPosition += entry.position * entry.impressions
+ } else {
+ orderedKeys.push(key)
+ buckets.set(key, {
+ clicks: entry.clicks,
+ impressions: entry.impressions,
+ weightedPosition: entry.position * entry.impressions,
+ })
+ }
+ }
+
+ return orderedKeys.map((key) => {
+ const entry = buckets.get(key)
+
+ return {
+ date: key,
+ clicks: Math.round(entry.clicks),
+ impressions: Math.round(entry.impressions),
+ ctr:
+ entry.impressions > 0
+ ? round((entry.clicks / entry.impressions) * 100, 2)
+ : 0,
+ position:
+ entry.impressions > 0
+ ? round(entry.weightedPosition / entry.impressions, 2)
+ : 0,
+ }
+ })
+}
+
+export const mapSeoTimeseries = (
+ series: SeoDateSeriesEntry[],
+ metrics: string[],
+ timezone: string,
+): TimeseriesRow[] =>
+ series
+ .filter((entry) => Boolean(entry.date))
+ .map((entry) => {
+ const values = mapSeoMetricValues(entry)
+ const row: TimeseriesRow = {
+ timestamp: toIsoTimestamp(entry.date, timezone),
+ }
+
+ for (const metric of metrics) {
+ row[metric] = values[metric as keyof SeoMetricValues]
+ }
+
+ return row
+ })
diff --git a/backend/apps/community/src/analytics/v2/registry/seo.ts b/backend/apps/community/src/analytics/v2/registry/seo.ts
new file mode 100644
index 000000000..7128783ee
--- /dev/null
+++ b/backend/apps/community/src/analytics/v2/registry/seo.ts
@@ -0,0 +1,193 @@
+import { UnprocessableEntityException } from '@nestjs/common'
+
+import { V2Filter } from '../query/filters.translator'
+
+/**
+ * SEO data is served by the Google Search Console API rather than ClickHouse,
+ * so it cannot join the column/sqlExpr registry in ./dimensions and ./metrics.
+ * These definitions mirror that registry's shape and lookup semantics to keep
+ * /v2/projects/:pid/seo/* consistent with the rest of the v2 surface.
+ */
+
+export type V2SeoGscDimension = 'query' | 'page' | 'country' | 'device'
+
+export interface V2SeoDimensionDef {
+ api: string
+ gsc: V2SeoGscDimension
+ description: string
+}
+
+export interface V2SeoMetricDef {
+ api: string
+ isDefault?: boolean
+ format: 'integer' | 'percent' | 'position'
+ description: string
+}
+
+export const V2_SEO_DIMENSIONS: V2SeoDimensionDef[] = [
+ {
+ api: 'query',
+ gsc: 'query',
+ description: 'Search query the site was surfaced for',
+ },
+ {
+ api: 'page',
+ gsc: 'page',
+ description: 'Landing page URL that appeared in search results',
+ },
+ {
+ api: 'country',
+ gsc: 'country',
+ description: 'Country the search was made from (ISO 3166-1 alpha-2 code)',
+ },
+ {
+ api: 'device',
+ gsc: 'device',
+ description: 'Device category the search was made on',
+ },
+]
+
+const V2_SEO_METRICS: V2SeoMetricDef[] = [
+ {
+ api: 'clicks',
+ isDefault: true,
+ format: 'integer',
+ description: 'Clicks through to the site from search results',
+ },
+ {
+ api: 'impressions',
+ isDefault: true,
+ format: 'integer',
+ description: 'Times a link to the site appeared in search results',
+ },
+ {
+ api: 'ctr',
+ isDefault: true,
+ format: 'percent',
+ description: 'Click-through rate, as a percentage of impressions',
+ },
+ {
+ api: 'position',
+ isDefault: true,
+ format: 'position',
+ description: 'Average position in search results',
+ },
+]
+
+export const listSeoDimensions = (): V2SeoDimensionDef[] => V2_SEO_DIMENSIONS
+
+export const listSeoMetrics = (): V2SeoMetricDef[] => V2_SEO_METRICS
+
+const findSeoDimension = (api: string): V2SeoDimensionDef | undefined =>
+ V2_SEO_DIMENSIONS.find((dimension) => dimension.api === api)
+
+export const getSeoBreakdownDimension = (api: string): V2SeoDimensionDef => {
+ const dimension = findSeoDimension(api)
+
+ if (!dimension) {
+ throw new UnprocessableEntityException(
+ `Unknown seo dimension '${api}'. Supported dimensions: ${V2_SEO_DIMENSIONS.map(
+ (d) => d.api,
+ ).join(', ')}`,
+ )
+ }
+
+ return dimension
+}
+
+export const getSeoMetric = (api: string): V2SeoMetricDef => {
+ const metric = V2_SEO_METRICS.find((m) => m.api === api)
+
+ if (!metric) {
+ throw new UnprocessableEntityException(
+ `Unknown seo metric '${api}'. Supported metrics: ${V2_SEO_METRICS.map(
+ (m) => m.api,
+ ).join(', ')}`,
+ )
+ }
+
+ return metric
+}
+
+export const getDefaultSeoMetrics = (): V2SeoMetricDef[] =>
+ V2_SEO_METRICS.filter((metric) => metric.isDefault)
+
+export const parseSeoMetricsParam = (
+ metrics: string | undefined,
+): V2SeoMetricDef[] => {
+ if (!metrics) {
+ return getDefaultSeoMetrics()
+ }
+
+ const names = [
+ ...new Set(
+ metrics
+ .split(',')
+ .map((name) => name.trim())
+ .filter(Boolean),
+ ),
+ ]
+
+ if (names.length === 0) {
+ return getDefaultSeoMetrics()
+ }
+
+ return names.map((name) => getSeoMetric(name))
+}
+
+/**
+ * Search Console orders rows by clicks descending and exposes no sort control,
+ * so this is the only ordering the seo breakdown can honour. It is accepted
+ * (rather than rejected outright) so callers can be explicit about it.
+ */
+export const SEO_SORT = 'clicks:desc'
+
+/**
+ * GSCService.parseFilters keys filters by their v1 URL names, where the keyword
+ * dimension is 'keywords'. v2 calls it 'query', after Search Console's own
+ * naming, so translate on the way down — the same v2 -> v1 hop the ClickHouse
+ * data types make through toV1FiltersJson.
+ */
+export const toGscFiltersJson = (filters: V2Filter[]): string | undefined => {
+ if (filters.length === 0) {
+ return undefined
+ }
+
+ return JSON.stringify(
+ filters.map((filter) => ({
+ ...filter,
+ dimension: filter.dimension === 'query' ? 'keywords' : filter.dimension,
+ })),
+ )
+}
+
+/**
+ * Search Console expresses filters as dimensionFilterGroups of scalar
+ * comparisons, so the array / null values the rest of v2 accepts have no
+ * equivalent here. Reject them rather than silently dropping the filter.
+ */
+export const validateSeoFilters = (filters: V2Filter[]): V2Filter[] => {
+ for (const filter of filters) {
+ if (!findSeoDimension(filter.dimension)) {
+ throw new UnprocessableEntityException(
+ `Unknown seo filter dimension '${filter.dimension}'. Supported dimensions: ${V2_SEO_DIMENSIONS.map(
+ (d) => d.api,
+ ).join(', ')}`,
+ )
+ }
+
+ if (Array.isArray(filter.value)) {
+ throw new UnprocessableEntityException(
+ `The seo filter on '${filter.dimension}' cannot take an array of values; Search Console only supports a single value per filter`,
+ )
+ }
+
+ if (filter.value === null) {
+ throw new UnprocessableEntityException(
+ `The seo filter on '${filter.dimension}' cannot take a null value; Search Console does not report unset dimension values`,
+ )
+ }
+ }
+
+ return filters
+}
diff --git a/backend/apps/community/src/analytics/v2/seo-v2.service.ts b/backend/apps/community/src/analytics/v2/seo-v2.service.ts
new file mode 100644
index 000000000..a8261e0a3
--- /dev/null
+++ b/backend/apps/community/src/analytics/v2/seo-v2.service.ts
@@ -0,0 +1,512 @@
+import {
+ BadRequestException,
+ ConflictException,
+ Injectable,
+ UnprocessableEntityException,
+} from '@nestjs/common'
+import dayjs from 'dayjs'
+import utc from 'dayjs/plugin/utc'
+
+import {
+ BrandedTrafficAnalytics,
+ GSC_ALL_TIME_DAYS,
+ GSCContext,
+ GSCService,
+ MAX_BRANDED_TRAFFIC_RANGE_DAYS,
+ MAX_FILTER_EXPRESSION_LENGTH,
+ MAX_FILTERS,
+ MAX_POSITION_ANALYTICS_RANGE_DAYS,
+ OPTIONAL_ANALYTICS_TIMEOUT_MS,
+ PositionAnalytics,
+} from '../../project/gsc.service'
+import { AnalyticsService } from '../analytics.service'
+import { TimeBucketType } from '../dto/getData.dto'
+import {
+ V2SeoBreakdownDto,
+ V2SeoRangeDto,
+ V2SeoSummaryDto,
+ V2SeoTimeseriesDto,
+ V2_SEO_TIME_BUCKETS,
+} from './dto/seo.dto'
+import { V2_DEFAULT_PERIOD, V2BaseQueryDto } from './dto/v2-base.dto'
+import { envelope, V2Envelope } from './mappers/envelope'
+import {
+ bucketSeoDateSeries,
+ mapSeoBreakdownRows,
+ mapSeoSummary,
+ mapSeoTimeseries,
+ SeoDateSeriesEntry,
+ SeoSummaryData,
+} from './mappers/seo.mapper'
+import { toIsoTimestamp, TimeseriesRow } from './mappers/timeseries.mapper'
+import { parseV2Filters, V2Filter } from './query/filters.translator'
+import {
+ getSeoBreakdownDimension,
+ listSeoDimensions,
+ listSeoMetrics,
+ parseSeoMetricsParam,
+ SEO_SORT,
+ toGscFiltersJson,
+ validateSeoFilters,
+} from './registry/seo'
+
+dayjs.extend(utc)
+
+const DEFAULT_SEO_BREAKDOWN_LIMIT = 30
+
+const INTRADAY_PERIODS = ['1h', 'today', 'yesterday', '1d']
+
+interface SeoTimeframe {
+ period: string | null
+ timeBucket: TimeBucketType
+ safeTimezone: string
+ groupFrom: string
+ groupTo: string
+ rangeDays: number
+}
+
+const SKIPPED = Symbol('skipped')
+
+/**
+ * Runs an expensive Search Console rollup under a deadline. A timeout aborts
+ * the in-flight paging and reports the panel as skipped; a genuine upstream
+ * failure still propagates, so a broken panel reads as broken rather than as
+ * "too much data".
+ */
+const resolveOptional = async <T>(
+ load: (signal: AbortSignal) => Promise<T>,
+): Promise<T | typeof SKIPPED> => {
+ const controller = new AbortController()
+ let timeout: ReturnType<typeof setTimeout> | undefined
+
+ const loading = load(controller.signal)
+
+ // Aborting rejects `loading` after the race has already settled on SKIPPED;
+ // this keeps that late rejection from surfacing as an unhandled rejection
+ // without stopping Promise.race from seeing a real, pre-deadline failure.
+ loading.catch(() => {})
+
+ try {
+ return await Promise.race([
+ loading,
+ new Promise<typeof SKIPPED>((resolve) => {
+ timeout = setTimeout(() => {
+ controller.abort()
+ resolve(SKIPPED)
+ }, OPTIONAL_ANALYTICS_TIMEOUT_MS)
+ }),
+ ])
+ } finally {
+ if (timeout) {
+ clearTimeout(timeout)
+ }
+ }
+}
+
+@Injectable()
+export class SeoV2Service {
+ constructor(
+ private readonly gscService: GSCService,
+ private readonly analyticsService: AnalyticsService,
+ ) {}
+
+ /**
+ * Search Console has to be connected and a property linked before any of the
+ * data endpoints can answer. Both are project configuration rather than a bad
+ * request, hence 409 rather than 400.
+ *
+ * Call this only after the request itself has been validated: a malformed
+ * filter is a 422 whether or not the project happens to be connected, and
+ * answering 409 first would send callers debugging their query down the
+ * wrong path.
+ */
+ private async requireContext(pid: string): Promise<GSCContext> {
+ const { connected, property } =
+ await this.gscService.getConnectionState(pid)
+
+ if (!connected) {
+ throw new ConflictException(
+ 'Google Search Console is not connected for this project',
+ )
+ }
+
+ if (!property) {
+ throw new ConflictException(
+ 'No Google Search Console property is linked to this project',
+ )
+ }
+
+ return this.gscService.getGSCContext(pid)
+ }
+
+ private prepareFilters(filters: string | undefined): {
+ appliedFilters: V2Filter[]
+ gscFilters: string | undefined
+ } {
+ const appliedFilters = validateSeoFilters(parseV2Filters(filters))
+
+ if (appliedFilters.length > MAX_FILTERS) {
+ throw new UnprocessableEntityException(
+ `Too many filters; at most ${MAX_FILTERS} may be applied at once`,
+ )
+ }
+
+ for (const filter of appliedFilters) {
+ if (String(filter.value).length > MAX_FILTER_EXPRESSION_LENGTH) {
+ throw new UnprocessableEntityException(
+ `The seo filter on '${filter.dimension}' has a value longer than ${MAX_FILTER_EXPRESSION_LENGTH} characters`,
+ )
+ }
+ }
+
+ // GSCService.parseFilters already understands the v2 filter shape, so the
+ // validated filters are handed straight back to it, mirroring how the
+ // ClickHouse data types translate v2 -> v1 JSON -> getFiltersQuery.
+ return { appliedFilters, gscFilters: toGscFiltersJson(appliedFilters) }
+ }
+
+ private resolveTimeframe(
+ dto: V2BaseQueryDto,
+ requestedBucket?: TimeBucketType,
+ ): SeoTimeframe {
+ const { from, to, timezone } = dto
+ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)
+
+ if (Boolean(from) !== Boolean(to)) {
+ throw new BadRequestException(
+ "The 'from' and 'to' parameters must be provided together",
+ )
+ }
+
+ const hasCustomRange = Boolean(from && to)
+ const period = hasCustomRange
+ ? null
+ : dto.period && dto.period !== 'custom'
+ ? dto.period
+ : V2_DEFAULT_PERIOD
+
+ const timeBucket =
+ requestedBucket ??
+ (period && INTRADAY_PERIODS.includes(period)
+ ? TimeBucketType.HOUR
+ : TimeBucketType.DAY)
+
+ // getGroupFromTo validates the bucket against the range, which neither an
+ // open-ended 'all' nor a caller-chosen custom range can satisfy.
+ const groupTimeBucket =
+ hasCustomRange || period === 'all' ? null : timeBucket
+ const diff = period === 'all' ? GSC_ALL_TIME_DAYS : undefined
+
+ const { groupFrom, groupTo } = this.analyticsService.getGroupFromTo(
+ hasCustomRange ? from : undefined,
+ hasCustomRange ? to : undefined,
+ groupTimeBucket,
+ period ?? undefined,
+ safeTimezone,
+ diff,
+ )
+
+ const rangeDays =
+ Math.abs(
+ dayjs(groupTo)
+ .startOf('day')
+ .diff(dayjs(groupFrom).startOf('day'), 'day'),
+ ) + 1
+
+ return { period, timeBucket, safeTimezone, groupFrom, groupTo, rangeDays }
+ }
+
+ private baseMeta(
+ pid: string,
+ timeframe: SeoTimeframe,
+ appliedFilters: V2Filter[],
+ ): Record<string, unknown> {
+ return {
+ pid,
+ period: timeframe.period,
+ from: toIsoTimestamp(timeframe.groupFrom, timeframe.safeTimezone),
+ to: toIsoTimestamp(timeframe.groupTo, timeframe.safeTimezone),
+ timezone: timeframe.safeTimezone,
+ appliedFilters,
+ }
+ }
+
+ async getStatus(
+ pid: string,
+ ): Promise<V2Envelope<{ connected: boolean; property: string | null }>> {
+ const state = await this.gscService.getConnectionState(pid)
+
+ return envelope(state, { pid })
+ }
+
+ /**
+ * Mirrors AnalyticsV2Service.getDimensions so `?type=seo` answers in the same
+ * shape as every other data type on the discovery endpoint.
+ */
+ getDimensions(): V2Envelope<{
+ dimensions: Record<string, unknown>[]
+ metrics: Record<string, unknown>[]
+ }> {
+ const dimensions = listSeoDimensions().map((dimension) => ({
+ name: dimension.api,
+ description: dimension.description,
+ filterOnly: false,
+ extraFields: [] as string[],
+ }))
+
+ const metrics = listSeoMetrics().map((metric) => ({
+ name: metric.api,
+ description: metric.description,
+ format: metric.format,
+ default: Boolean(metric.isDefault),
+ }))
+
+ return envelope({ dimensions, metrics }, { type: 'seo' })
+ }
+
+ async getSummary(
+ pid: string,
+ dto: V2SeoSummaryDto,
+ ): Promise<V2Envelope<SeoSummaryData>> {
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const timeframe = this.resolveTimeframe(dto)
+ const ctx = await this.requireContext(pid)
+ const { groupFrom, groupTo } = timeframe
+
+ const fromDate = dayjs(groupFrom)
+ const durationMs = dayjs(groupTo).diff(fromDate)
+ const previousTo = fromDate
+ .subtract(1, 'millisecond')
+ .format('YYYY-MM-DD HH:mm:ss')
+ const previousFrom = fromDate
+ .subtract(durationMs, 'millisecond')
+ .format('YYYY-MM-DD HH:mm:ss')
+
+ const [current, previous] = await Promise.all([
+ this.gscService.getSummary(pid, groupFrom, groupTo, gscFilters, ctx),
+ this.gscService
+ .getSummary(pid, previousFrom, previousTo, gscFilters, ctx)
+ .catch(() => null),
+ ])
+
+ return envelope(mapSeoSummary(current, previous), {
+ ...this.baseMeta(pid, timeframe, appliedFilters),
+ metrics: listSeoMetrics().map((metric) => metric.api),
+ })
+ }
+
+ async getTimeseries(
+ pid: string,
+ dto: V2SeoTimeseriesDto,
+ ): Promise<V2Envelope<TimeseriesRow[]>> {
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const metrics = parseSeoMetricsParam(dto.metrics).map(
+ (metric) => metric.api,
+ )
+ const timeframe = this.resolveTimeframe(
+ dto,
+ dto.timeBucket as TimeBucketType | undefined,
+ )
+ const ctx = await this.requireContext(pid)
+
+ // Search Console only serves hourly and daily rows; wider buckets are
+ // rolled up from the daily series rather than requested upstream.
+ const series = (await this.gscService.getDateSeries(
+ pid,
+ timeframe.groupFrom,
+ timeframe.groupTo,
+ timeframe.timeBucket === TimeBucketType.HOUR ? 'hour' : 'day',
+ gscFilters,
+ ctx,
+ )) as SeoDateSeriesEntry[]
+
+ const bucketed = bucketSeoDateSeries(series, timeframe.timeBucket)
+
+ return envelope(
+ mapSeoTimeseries(bucketed, metrics, timeframe.safeTimezone),
+ {
+ ...this.baseMeta(pid, timeframe, appliedFilters),
+ metrics,
+ timeBucket: timeframe.timeBucket,
+ allowedTimeBuckets: [...V2_SEO_TIME_BUCKETS],
+ },
+ )
+ }
+
+ async getBreakdown(
+ pid: string,
+ dto: V2SeoBreakdownDto,
+ ): Promise<V2Envelope<Record<string, unknown>[]>> {
+ const dimension = getSeoBreakdownDimension(dto.dimension)
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const metrics = parseSeoMetricsParam(dto.metrics).map(
+ (metric) => metric.api,
+ )
+ const timeframe = this.resolveTimeframe(dto)
+ const limit = dto.limit ?? DEFAULT_SEO_BREAKDOWN_LIMIT
+ const offset = dto.offset ?? 0
+ const ctx = await this.requireContext(pid)
+ const { groupFrom, groupTo } = timeframe
+
+ const rows = await this.fetchBreakdownRows(
+ dimension.gsc,
+ pid,
+ groupFrom,
+ groupTo,
+ limit,
+ offset,
+ gscFilters,
+ ctx,
+ )
+
+ return envelope(mapSeoBreakdownRows(dimension.gsc, rows, metrics), {
+ ...this.baseMeta(pid, timeframe, appliedFilters),
+ dimension: dimension.api,
+ metrics,
+ limit,
+ offset,
+ sort: SEO_SORT,
+ })
+ }
+
+ private fetchBreakdownRows(
+ dimension: 'query' | 'page' | 'country' | 'device',
+ pid: string,
+ from: string,
+ to: string,
+ limit: number,
+ offset: number,
+ filters: string | undefined,
+ ctx: GSCContext,
+ ) {
+ if (dimension === 'query') {
+ return this.gscService.getKeywords(
+ pid,
+ from,
+ to,
+ limit,
+ offset,
+ filters,
+ undefined,
+ ctx,
+ )
+ }
+
+ if (dimension === 'page') {
+ return this.gscService.getTopPages(
+ pid,
+ from,
+ to,
+ limit,
+ offset,
+ filters,
+ undefined,
+ ctx,
+ )
+ }
+
+ if (dimension === 'country') {
+ return this.gscService.getTopCountries(
+ pid,
+ from,
+ to,
+ limit,
+ offset,
+ filters,
+ ctx,
+ )
+ }
+
+ return this.gscService.getTopDevices(
+ pid,
+ from,
+ to,
+ limit,
+ offset,
+ filters,
+ ctx,
+ )
+ }
+
+ async getBrandedTraffic(
+ pid: string,
+ dto: V2SeoRangeDto,
+ ): Promise<V2Envelope<BrandedTrafficAnalytics | null>> {
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const timeframe = this.resolveTimeframe(dto)
+ const ctx = await this.requireContext(pid)
+ const meta = this.baseMeta(pid, timeframe, appliedFilters)
+
+ if (timeframe.rangeDays > MAX_BRANDED_TRAFFIC_RANGE_DAYS) {
+ return envelope(null, {
+ ...meta,
+ skipped: true,
+ skippedReason: 'range_too_large',
+ maxRangeDays: MAX_BRANDED_TRAFFIC_RANGE_DAYS,
+ })
+ }
+
+ const result = await resolveOptional((signal) =>
+ this.gscService.getBrandedTraffic(
+ pid,
+ timeframe.groupFrom,
+ timeframe.groupTo,
+ gscFilters,
+ ctx,
+ signal,
+ ),
+ )
+
+ if (result === SKIPPED) {
+ return envelope(null, {
+ ...meta,
+ skipped: true,
+ skippedReason: 'timeout',
+ timeoutMs: OPTIONAL_ANALYTICS_TIMEOUT_MS,
+ })
+ }
+
+ return envelope(result, { ...meta, skipped: false })
+ }
+
+ async getPositions(
+ pid: string,
+ dto: V2SeoRangeDto,
+ ): Promise<V2Envelope<PositionAnalytics | null>> {
+ const { appliedFilters, gscFilters } = this.prepareFilters(dto.filters)
+ const timeframe = this.resolveTimeframe(dto)
+ const ctx = await this.requireContext(pid)
+ const meta = this.baseMeta(pid, timeframe, appliedFilters)
+
+ if (timeframe.rangeDays > MAX_POSITION_ANALYTICS_RANGE_DAYS) {
+ return envelope(null, {
+ ...meta,
+ skipped: true,
+ skippedReason: 'range_too_large',
+ maxRangeDays: MAX_POSITION_ANALYTICS_RANGE_DAYS,
+ })
+ }
+
+ const result = await resolveOptional((signal) =>
+ this.gscService.getPositionAnalytics(
+ pid,
+ timeframe.groupFrom,
+ timeframe.groupTo,
+ gscFilters,
+ ctx,
+ signal,
+ ),
+ )
+
+ if (result === SKIPPED) {
+ return envelope(null, {
+ ...meta,
+ skipped: true,
+ skippedReason: 'timeout',
+ timeoutMs: OPTIONAL_ANALYTICS_TIMEOUT_MS,
+ })
+ }
+
+ return envelope(result, { ...meta, skipped: false })
+ }
+}
diff --git a/backend/apps/community/src/project/gsc.service.ts b/backend/apps/community/src/project/gsc.service.ts
index b2a751f52..dc4350e23 100644
--- a/backend/apps/community/src/project/gsc.service.ts
+++ b/backend/apps/community/src/project/gsc.service.ts
@@ -39,11 +39,17 @@ const ENCRYPTION_KEY = deriveKey('gsc-token')
const MAX_ROW_LIMIT = 25000
const MAX_BRANDED_PAGES = 10
-const MAX_FILTER_EXPRESSION_LENGTH = 500
-const MAX_FILTERS = 20
-const MAX_BRANDED_TRAFFIC_RANGE_DAYS = 31
-const MAX_POSITION_ANALYTICS_RANGE_DAYS = 31
-const OPTIONAL_ANALYTICS_TIMEOUT_MS = 12000
+export const MAX_FILTER_EXPRESSION_LENGTH = 500
+export const MAX_FILTERS = 20
+export const MAX_BRANDED_TRAFFIC_RANGE_DAYS = 31
+export const MAX_POSITION_ANALYTICS_RANGE_DAYS = 31
+export const OPTIONAL_ANALYTICS_TIMEOUT_MS = 12000
+
+/**
+ * Search Console keeps roughly 16 months of history, so an 'all' period is
+ * resolved against a fixed window rather than the project's first event.
+ */
+export const GSC_ALL_TIME_DAYS = 480
const IMPRESSION_POSITION_BUCKETS = [
{ key: 'pos1To3', label: '1-3' },
@@ -67,13 +73,8 @@ type OrganicPositionSeriesEntry = { date: string } & Record<
OrganicPositionBucketKey,
number
>
-type BrandedTrafficAnalytics = { branded: number; nonBranded: number }
-type SkippedBrandedAnalytics = {
- skipped: true
- branded: null
- nonBranded: null
-}
-type PositionAnalytics = {
+export type BrandedTrafficAnalytics = { branded: number; nonBranded: number }
+export type PositionAnalytics = {
impressionsByPosition: {
key: ImpressionPositionBucketKey
label: string
@@ -82,23 +83,6 @@ type PositionAnalytics = {
}[]
organicPositions: OrganicPositionSeriesEntry[]
}
-type SkippedPositionAnalytics = {
- skipped: true
- impressionsByPosition: null
- organicPositions: null
-}
-
-const SKIPPED_BRANDED_ANALYTICS: SkippedBrandedAnalytics = {
- skipped: true,
- branded: null,
- nonBranded: null,
-}
-
-const SKIPPED_POSITION_ANALYTICS: SkippedPositionAnalytics = {
- skipped: true,
- impressionsByPosition: null,
- organicPositions: null,
-}
const initialImpressionPositionBuckets = (): Record<
ImpressionPositionBucketKey,
@@ -140,32 +124,6 @@ const getOrganicPositionBucketKey = (
return 'pos51Plus'
}
-const resolveOptionalAnalytics = async <T>(
- load: (signal: AbortSignal) => Promise<T>,
- fallback: T,
-): Promise<T> => {
- const controller = new AbortController()
- let timeout: ReturnType<typeof setTimeout> | undefined
-
- try {
- return await Promise.race([
- load(controller.signal),
- new Promise<T>((resolve) => {
- timeout = setTimeout(() => {
- controller.abort()
- resolve(fallback)
- }, OPTIONAL_ANALYTICS_TIMEOUT_MS)
- }),
- ])
- } catch {
- return fallback
- } finally {
- if (timeout) {
- clearTimeout(timeout)
- }
- }
-}
-
type GSCRow = {
keys: string[]
clicks?: number
@@ -174,7 +132,7 @@ type GSCRow = {
position?: number
}
-type GSCContext = {
+export type GSCContext = {
sc: ReturnType<typeof searchconsole>
siteUrl: string
}
@@ -428,6 +386,28 @@ export class GSCService {
return !_isEmpty(tokens?.refresh_token || tokens?.access_token)
}
+ /**
+ * Whether the project can currently be queried: Search Console has to be
+ * configured on this instance, an account connected and a property linked.
+ * Unlike getStatus this needs no account email, so it is safe to expose to
+ * anyone with project read access.
+ */
+ async getConnectionState(
+ pid: string,
+ ): Promise<{ connected: boolean; property: string | null }> {
+ if (!this.isAvailable()) {
+ return { connected: false, property: null }
+ }
+
+ const tokens = await this.getStoredTokens(pid)
+ const connected = !_isEmpty(tokens?.refresh_token || tokens?.access_token)
+
+ return {
+ connected,
+ property: connected ? tokens.property_uri || null : null,
+ }
+ }
+
async getStatus(pid: string): Promise<{
connected: boolean
email: string | null
@@ -482,7 +462,7 @@ export class GSCService {
return oauth2Client
}
- private async getGSCContext(pid: string): Promise<GSCContext> {
+ async getGSCContext(pid: string): Promise<GSCContext> {
const tokens = await this.getStoredTokens(pid)
if (_isEmpty(tokens) || _isEmpty(tokens.property_uri)) {
throw new BadRequestException(
@@ -1245,101 +1225,4 @@ export class GSCService {
)
}
}
-
- async getDashboard(
- pid: string,
- from: string,
- to: string,
- timeBucket?: string,
- filtersStr?: string,
- ) {
- if (!this.isAvailable()) {
- return { notConnected: true }
- }
-
- const connected = await this.isConnected(pid)
- if (!connected) {
- return { notConnected: true }
- }
-
- const tokens = await this.getStoredTokens(pid)
- if (_isEmpty(tokens.property_uri)) {
- return { notConnected: true, noProperty: true }
- }
-
- let ctx: GSCContext
- try {
- ctx = await this.getGSCContext(pid)
- } catch {
- return { notConnected: true }
- }
-
- const fromDate = dayjs(from)
- const toDate = dayjs(to)
- const durationMs = toDate.diff(fromDate)
- const rangeDays =
- Math.abs(toDate.startOf('day').diff(fromDate.startOf('day'), 'day')) + 1
- const shouldLoadBrandedTraffic = rangeDays <= MAX_BRANDED_TRAFFIC_RANGE_DAYS
- const shouldLoadPositionAnalytics =
- rangeDays <= MAX_POSITION_ANALYTICS_RANGE_DAYS
- const prevTo = fromDate
- .subtract(1, 'millisecond')
- .format('YYYY-MM-DD HH:mm:ss')
- const prevFrom = fromDate
- .subtract(durationMs, 'millisecond')
- .format('YYYY-MM-DD HH:mm:ss')
-
- const [
- summary,
- previousSummary,
- dateSeries,
- topPages,
- topQueries,
- topCountries,
- topDevices,
- brandedTraffic,
- positionAnalytics,
- ] = await Promise.all([
- this.getSummary(pid, from, to, filtersStr, ctx),
- this.getSummary(pid, prevFrom, prevTo, filtersStr, ctx).catch(() => null),
- this.getDateSeries(pid, from, to, timeBucket, filtersStr, ctx),
- this.getTopPages(pid, from, to, 50, 0, filtersStr, undefined, ctx),
- this.getKeywords(pid, from, to, 50, 0, filtersStr, undefined, ctx),
- this.getTopCountries(pid, from, to, 50, 0, filtersStr, ctx),
- this.getTopDevices(pid, from, to, 50, 0, filtersStr, ctx),
- shouldLoadBrandedTraffic
- ? resolveOptionalAnalytics<
- BrandedTrafficAnalytics | SkippedBrandedAnalytics
- >(
- (signal) =>
- this.getBrandedTraffic(pid, from, to, filtersStr, ctx, signal),
- SKIPPED_BRANDED_ANALYTICS,
- )
- : Promise.resolve(SKIPPED_BRANDED_ANALYTICS),
- shouldLoadPositionAnalytics
- ? resolveOptionalAnalytics<
- PositionAnalytics | SkippedPositionAnalytics
- >(
- (signal) =>
- this.getPositionAnalytics(pid, from, to, filtersStr, ctx, signal),
- SKIPPED_POSITION_ANALYTICS,
- )
- : Promise.resolve(SKIPPED_POSITION_ANALYTICS),
- ])
-
- return {
- notConnected: false,
- summary,
- previousSummary,
- dateSeries,
- topPages,
- topQueries,
- topCountries,
- topDevices,
- brandedTraffic,
- positionAnalyticsSkipped: 'skipped' in positionAnalytics,
- impressionsByPosition: positionAnalytics.impressionsByPosition,
- organicPositions: positionAnalytics.organicPositions,
- }
- }
}
diff --git a/docs/content/docs/api/stats-v2.mdx b/docs/content/docs/api/stats-v2.mdx
index a321df12b..de46bf774 100644
--- a/docs/content/docs/api/stats-v2.mdx
+++ b/docs/content/docs/api/stats-v2.mdx
@@ -63,6 +63,7 @@ Every endpoint returns the same envelope:
| performance | `load_time`, `ttfb`, `dns`, `tls`, `connection`, `response`, `render`, `dom_load` — all in seconds, aggregated by `measure` |
| errors | `occurrences`, `affected_users` |
| captcha | `events` (breakdown), `generated`, `passed`, `failed`, `validation_failed`, `replayed` (timeseries/summary) |
+| seo | `clicks`, `impressions`, `ctr` (percentage), `position` (average search position) — all four returned by default |
### Dimensions
@@ -91,6 +92,7 @@ Dimensions use human-readable names (mapped internally onto the v1 short codes):
| `page_property` | `tag:key:<key>` | filter-only, takes a `key` |
| `error_name` / `error_message` / `error_filename` | — | errors, filter-only |
| `captcha_event` / `captcha_difficulty` / `captcha_reason` / `solve_time` | — | captcha only |
+| `query` | `keywords` | seo only — the search query |
Which dimensions apply to which data type is discoverable via [`GET /v2/projects/:pid/dimensions`](#get-v2projectspiddimensions).
@@ -116,6 +118,8 @@ Unknown dimensions or operators are rejected with a `422` and a message listing
Breakdown and list endpoints accept `limit` (default 30) and `offset`. Breakdown responses include `meta.total` — the total number of dimension values — for pagination. Breakdowns also accept `sort=field:direction` where `field` is `value` or any selected metric and `direction` is `asc` or `desc` (default: first selected metric, descending).
+The `seo` data type is the exception on both counts: Google Search Console reports no row total and offers no sort control, so `/seo/breakdown` omits `meta.total` and always orders by clicks descending. Page through it until you get fewer rows than you asked for.
+
### Measure (performance)
Performance endpoints accept `measure`: `median` (default), `average`, `p75`, `p95`. The special `quantiles` measure is only meaningful on `/performance/timeseries`, where it returns `p50`/`p75`/`p95` of the total load time.
@@ -323,6 +327,203 @@ Captcha counters per time bucket. Metrics: `generated`, `passed`, `failed`, `val
Captcha events grouped by `country`, `browser`, `os`, `device` (passed captchas only), or `captcha_event`, `captcha_difficulty`, `captcha_reason`, `solve_time`.
+## SEO endpoints
+
+SEO data comes from [Google Search Console](/integrations/google-search-console) rather than from your Swetrix events, so these endpoints behave a little differently from the rest of v2. The differences are all forced by the upstream API and are called out below.
+
+Search Console must be connected to the project and one of its properties linked. Until both are true, every `seo` endpoint except `/seo/status` returns `409 Conflict`:
+
+```json title="Response (409)"
+{
+ "statusCode": 409,
+ "message": "Google Search Console is not connected for this project"
+}
+```
+
+Two further caveats worth knowing before you build against these:
+
+- **Data lags.** Search Console is typically 2–3 days behind, so recent days may be empty or incomplete.
+- **Retention is ~16 months.** `period=all` resolves to the last 480 days rather than your project's full history.
+
+### GET /v2/projects/:pid/seo/status
+
+Whether the project can serve SEO data at all. Poll this before the others to tell "not connected" apart from "no data".
+
+```bash
+curl 'https://api.swetrix.com/v2/projects/YOUR_PROJECT_ID/seo/status' \
+ -H "X-Api-Key: ${SWETRIX_API_KEY}"
+```
+
+```json title="Response"
+{
+ "data": { "connected": true, "property": "sc-domain:example.com" },
+ "meta": { "pid": "YOUR_PROJECT_ID" }
+}
+```
+
+`connected` reports whether a Google account is linked; `property` is the Search Console property being queried, and is `null` when an account is connected but no property has been picked yet. Both must be set for the data endpoints to answer.
+
+### GET /v2/projects/:pid/seo/summary
+
+Clicks, impressions, CTR and average position for the selected period, the previous period of the same length, and the change between them.
+
+```bash
+curl 'https://api.swetrix.com/v2/projects/YOUR_PROJECT_ID/seo/summary?period=7d' \
+ -H "X-Api-Key: ${SWETRIX_API_KEY}"
+```
+
+```json title="Response"
+{
+ "data": {
+ "current": { "clicks": 412, "impressions": 18320, "ctr": 2.25, "position": 12.4 },
+ "previous": { "clicks": 388, "impressions": 17010, "ctr": 2.28, "position": 13.1 },
+ "change": { "clicks": 24, "impressions": 1310, "ctr": -0.03, "position": -0.7 }
+ },
+ "meta": {
+ "pid": "YOUR_PROJECT_ID",
+ "metrics": ["clicks", "impressions", "ctr", "position"],
+ "period": "7d",
+ "timezone": "Etc/GMT",
+ "appliedFilters": []
+ }
+}
+```
+
+`change` is the absolute difference, as everywhere else in v2. Note that a _falling_ `position` is an improvement.
+
+### GET /v2/projects/:pid/seo/timeseries
+
+SEO metrics grouped by time bucket, as rows with ISO 8601 timestamps.
+
+Parameters: `period`/`from`+`to`, `timezone`, `timeBucket`, `metrics`, `filters`.
+
+Search Console reports nothing below hourly granularity, so `timeBucket` here accepts only `hour`, `day` (default), `month` and `year` — `minute` is rejected with a `422`. Hourly and daily rows come straight from Search Console; `month` and `year` are rolled up by Swetrix, summing clicks and impressions, recomputing CTR from those totals, and averaging position weighted by impressions (none of the three are additive).
+
+```bash
+curl 'https://api.swetrix.com/v2/projects/YOUR_PROJECT_ID/seo/timeseries?period=7d&metrics=clicks,impressions&timezone=Europe/Kyiv' \
+ -H "X-Api-Key: ${SWETRIX_API_KEY}"
+```
+
+```json title="Response"
+{
+ "data": [
+ { "timestamp": "2026-07-01T00:00:00+03:00", "clicks": 61, "impressions": 2604 },
+ { "timestamp": "2026-07-02T00:00:00+03:00", "clicks": 58, "impressions": 2511 }
+ ],
+ "meta": {
+ "pid": "YOUR_PROJECT_ID",
+ "metrics": ["clicks", "impressions"],
+ "timeBucket": "day",
+ "allowedTimeBuckets": ["hour", "day", "month", "year"],
+ "period": "7d",
+ "timezone": "Europe/Kyiv",
+ "appliedFilters": []
+ }
+}
+```
+
+### GET /v2/projects/:pid/seo/breakdown
+
+SEO metrics grouped by **one dimension** — `query`, `page`, `country` or `device`.
+
+Parameters: `dimension` (required), `metrics` (default: all four), `limit` (max 100), `offset`, plus the usual time range and `filters`.
+
+```bash
+curl 'https://api.swetrix.com/v2/projects/YOUR_PROJECT_ID/seo/breakdown?dimension=query&period=4w&limit=2' \
+ -H "X-Api-Key: ${SWETRIX_API_KEY}"
+```
+
+```json title="Response"
+{
+ "data": [
+ { "value": "swetrix", "clicks": 184, "impressions": 2103, "ctr": 8.75, "position": 1.4 },
+ {
+ "value": "google analytics alternative",
+ "clicks": 96,
+ "impressions": 8801,
+ "ctr": 1.09,
+ "position": 9.2
+ }
+ ],
+ "meta": {
+ "pid": "YOUR_PROJECT_ID",
+ "dimension": "query",
+ "metrics": ["clicks", "impressions", "ctr", "position"],
+ "limit": 2,
+ "offset": 0,
+ "sort": "clicks:desc",
+ "period": "4w",
+ "timezone": "Etc/GMT",
+ "appliedFilters": []
+ }
+}
+```
+
+Notes:
+
+- **No `meta.total` and no `sort`.** Search Console neither counts matching rows nor lets you order them, so rows always come back by clicks descending. `sort` is accepted only as `clicks:desc`, so you can be explicit; anything else is a `422` rather than a silently ignored parameter. Page with `limit`/`offset` until a page comes back short.
+- **`country` is alpha-2.** Search Console reports alpha-3 (`usa`); Swetrix normalises to the alpha-2 (`US`) that `country` means everywhere else in v2.
+- Combine `dimension` with a filter to drill in — the queries a given page ranks for are `?dimension=query&filters=[{"dimension":"page","operator":"is","value":"https://example.com/blog"}]`, and the pages ranking for a query are the mirror image.
+
+### GET /v2/projects/:pid/seo/branded-traffic
+
+Clicks split by whether the search query contained one of the project's brand keywords (configured in project settings; Swetrix falls back to the project name and domain).
+
+```json title="Response (data)"
+{ "branded": 260, "nonBranded": 152 }
+```
+
+Returns `data: null` with `meta.skipped: true` when the rollup was not run — see [skipped rollups](#skipped-rollups).
+
+### GET /v2/projects/:pid/seo/positions
+
+Impressions bucketed by search position, plus the daily count of ranking queries per position bucket.
+
+```json title="Response (data, truncated)"
+{
+ "impressionsByPosition": [
+ { "key": "pos1To3", "label": "1-3", "impressions": 4120, "percentage": 22.5 },
+ { "key": "pos4To10", "label": "4-10", "impressions": 7330, "percentage": 40 }
+ ],
+ "organicPositions": [
+ {
+ "date": "2026-07-01",
+ "pos1To3": 12,
+ "pos4To10": 40,
+ "pos11To20": 61,
+ "pos21To50": 88,
+ "pos51Plus": 24
+ }
+ ]
+}
+```
+
+`impressionsByPosition` buckets are `pos1To3`, `pos4To10`, `pos11To20`, `pos21Plus`; `organicPositions` splits the tail further into `pos21To50` and `pos51Plus`. Returns `data: null` with `meta.skipped: true` when the rollup was not run.
+
+### Skipped rollups
+
+`/seo/branded-traffic` and `/seo/positions` have to page through every query in the range, which is slow and expensive against Search Console's quota. Rather than let them hang, Swetrix skips them and says so in `meta`:
+
+```json title="Response"
+{
+ "data": null,
+ "meta": {
+ "pid": "YOUR_PROJECT_ID",
+ "skipped": true,
+ "skippedReason": "range_too_large",
+ "maxRangeDays": 31,
+ "period": "3M",
+ "timezone": "Etc/GMT",
+ "appliedFilters": []
+ }
+}
+```
+
+- `skippedReason: "range_too_large"` — the range exceeds `meta.maxRangeDays` (31). Narrow the range.
+- `skippedReason: "timeout"` — Search Console did not answer within `meta.timeoutMs`. Retry, or narrow the range.
+
+On a successful run `meta.skipped` is `false` and `data` is populated. A skip is not an error — an actual upstream failure still returns a `5xx`.
+
## Error endpoints
### GET /v2/projects/:pid/errors
@@ -430,7 +631,7 @@ Paginated sessions that reached a funnel `step` (1-indexed). `dropoff=true` retu
### GET /v2/projects/:pid/dimensions
-Machine-readable list of the dimensions and metrics available for a data type (`?type=traffic|performance|captcha|errors`) — build dashboard UIs against this instead of hardcoding.
+Machine-readable list of the dimensions and metrics available for a data type (`?type=traffic|performance|captcha|errors|seo`) — build dashboard UIs against this instead of hardcoding.
```json title="Response (data, truncated)"
{
@@ -478,6 +679,7 @@ Distinct recorded values for a dimension — for filter autocompletion (`?type=t
| `GET /v1/log/funnel` / `/log/funnel-sessions` | `/funnel` / `/funnel/sessions` |
| `GET /v1/log/live-visitors` + `/log/hb` | `/live-visitors` (merged) |
| `GET /v1/log/filters` / `/log/errors-filters` / `/log/filters/versions` | `/dimensions/:dimension/values` |
+| `GET /v1/log/keywords` | `/seo/breakdown?dimension=query` |
Key differences:
@@ -487,4 +689,6 @@ Key differences:
4. **Everything is wrapped** in `{ data, meta }` and breakdowns/lists are paginated server-side.
5. `take`/`skip` are now `limit`/`offset`.
-Still v1-only: GSC/keywords endpoints, bot statistics, session replays, `generalStats`, multi-project `birdseye` (`pids` array), and all data ingestion endpoints.
+`GET /v1/log/keywords` still works, but it only ever returned the top queries. The `seo` endpoints cover the whole Search Console integration, so prefer them for new code.
+
+Still v1-only: bot statistics, session replays, `generalStats`, multi-project `birdseye` (`pids` array), and all data ingestion endpoints.
diff --git a/web/app/api/api.server.ts b/web/app/api/api.server.ts
index a973224ff..e9a0dd13a 100644
--- a/web/app/api/api.server.ts
+++ b/web/app/api/api.server.ts
@@ -1881,196 +1881,6 @@ export async function getGSCKeywordsServer(
)
}
-interface GSCDateSeriesEntry {
- date: string
- clicks: number
- impressions: number
- ctr: number
- position: number
-}
-
-interface GSCTopPageEntry {
- page: string
- clicks: number
- impressions: number
- ctr: number
- position: number
-}
-
-interface GSCTopQueryEntry {
- name: string
- count: number
- impressions: number
- position: number
- ctr: number
-}
-
-interface GSCTopCountryEntry {
- country: string
- clicks: number
- impressions: number
- ctr: number
- position: number
-}
-
-interface GSCTopDeviceEntry {
- device: string
- clicks: number
- impressions: number
- ctr: number
- position: number
-}
-
-type GSCImpressionPositionBucketKey =
- | 'pos1To3'
- | 'pos4To10'
- | 'pos11To20'
- | 'pos21Plus'
-
-type GSCOrganicPositionBucketKey =
- | 'pos1To3'
- | 'pos4To10'
- | 'pos11To20'
- | 'pos21To50'
- | 'pos51Plus'
-
-interface GSCImpressionsByPositionEntry {
- key: GSCImpressionPositionBucketKey
- label: string
- impressions: number
- percentage: number
-}
-
-type GSCOrganicPositionEntry = { date: string } & Record<
- GSCOrganicPositionBucketKey,
- number
->
-
-interface GSCBrandedTraffic {
- branded: number
- nonBranded: number
- skipped?: false
-}
-
-interface GSCSkippedBrandedTraffic {
- skipped: true
- branded: null
- nonBranded: null
-}
-
-export interface GSCDashboardResponse {
- notConnected?: boolean
- noProperty?: boolean
- summary?: {
- clicks: number
- impressions: number
- ctr: number
- position: number
- }
- previousSummary?: {
- clicks: number
- impressions: number
- ctr: number
- position: number
- } | null
- dateSeries?: GSCDateSeriesEntry[]
- topPages?: GSCTopPageEntry[]
- topQueries?: GSCTopQueryEntry[]
- topCountries?: GSCTopCountryEntry[]
- topDevices?: GSCTopDeviceEntry[]
- brandedTraffic?: GSCBrandedTraffic | GSCSkippedBrandedTraffic
- positionAnalyticsSkipped?: boolean
- impressionsByPosition?: GSCImpressionsByPositionEntry[] | null
- organicPositions?: GSCOrganicPositionEntry[] | null
-}
-
-export async function getGSCDashboardServer(
- request: Request,
- pid: string,
- params: {
- period?: string
- from?: string
- to?: string
- timezone?: string
- password?: string
- timeBucket?: string
- filters?: V2Filter[]
- } = {},
-): Promise<ServerFetchResult<GSCDashboardResponse>> {
- const queryParams = new URLSearchParams()
- queryParams.append('pid', pid)
- queryParams.append('period', params.period || '7d')
- if (params.from) queryParams.append('from', params.from)
- if (params.to) queryParams.append('to', params.to)
- if (params.timezone) queryParams.append('timezone', params.timezone)
- if (params.timeBucket) queryParams.append('timeBucket', params.timeBucket)
- if (params.filters)
- queryParams.append('filters', serializeFiltersForUrl(params.filters))
-
- const headers: Record<string, string> = {}
- if (params.password) {
- headers['x-password'] = params.password
- }
-
- return serverFetch<GSCDashboardResponse>(
- request,
- `log/gsc-dashboard?${queryParams.toString()}`,
- {
- headers,
- timeoutMs: 60000,
- },
- )
-}
-
-export interface GSCDetailsResponse {
- type: 'queries' | 'pages' | 'none'
- data: Array<{
- name?: string
- page?: string
- count?: number
- clicks?: number
- impressions: number
- ctr: number
- position: number
- }>
-}
-
-export async function getGSCDetailsServer(
- request: Request,
- pid: string,
- params: {
- period?: string
- from?: string
- to?: string
- timezone?: string
- password?: string
- page?: string
- query?: string
- } = {},
-): Promise<ServerFetchResult<GSCDetailsResponse>> {
- const queryParams = new URLSearchParams()
- queryParams.append('pid', pid)
- queryParams.append('period', params.period || '7d')
- if (params.from) queryParams.append('from', params.from)
- if (params.to) queryParams.append('to', params.to)
- if (params.timezone) queryParams.append('timezone', params.timezone)
- if (params.page) queryParams.append('page', params.page)
- if (params.query) queryParams.append('query', params.query)
-
- const headers: Record<string, string> = {}
- if (params.password) {
- headers['x-password'] = params.password
- }
-
- return serverFetch<GSCDetailsResponse>(
- request,
- `log/gsc-details?${queryParams.toString()}`,
- {
- headers,
- },
- )
-}
-
// ============================================================================
// MARK: Revenue API
// ============================================================================
diff --git a/web/app/api/v2/endpoints.ts b/web/app/api/v2/endpoints.ts
index 4360fc84f..d78521323 100644
--- a/web/app/api/v2/endpoints.ts
+++ b/web/app/api/v2/endpoints.ts
@@ -10,6 +10,10 @@ import {
MetricSums,
PagePropertyRow,
PerformanceSummaryData,
+ SeoBrandedTrafficData,
+ SeoPositionsData,
+ SeoStatusData,
+ SeoSummaryData,
TimeseriesRow,
TrafficSummaryData,
V2CommonParams,
@@ -24,7 +28,9 @@ type SummaryData<T extends V2DataType> = T extends 'traffic'
? PerformanceSummaryData
: T extends 'captcha'
? CaptchaSummaryData
- : Record<string, unknown>
+ : T extends 'seo'
+ ? SeoSummaryData
+ : Record<string, unknown>
export const getSummary = <T extends V2DataType>(
pid: string,
@@ -70,6 +76,33 @@ export const getBreakdown = (
signal,
)
+export const getSeoStatus = (pid: string, signal?: AbortSignal) =>
+ fetchV2<SeoStatusData>(`projects/${pid}/seo/status`, {}, signal)
+
+// Both of the below return `data: null` with `meta.skipped` when the range is
+// too wide or Search Console did not answer within the deadline.
+export const getSeoBrandedTraffic = (
+ pid: string,
+ params: Common,
+ signal?: AbortSignal,
+) =>
+ fetchV2<SeoBrandedTrafficData | null>(
+ `projects/${pid}/seo/branded-traffic`,
+ params,
+ signal,
+ )
+
+export const getSeoPositions = (
+ pid: string,
+ params: Common,
+ signal?: AbortSignal,
+) =>
+ fetchV2<SeoPositionsData | null>(
+ `projects/${pid}/seo/positions`,
+ params,
+ signal,
+ )
+
export const getCustomEvents = (
pid: string,
params: Common & { limit?: number; offset?: number },
diff --git a/web/app/api/v2/types.ts b/web/app/api/v2/types.ts
index a0c9921ce..f39aad2ef 100644
--- a/web/app/api/v2/types.ts
+++ b/web/app/api/v2/types.ts
@@ -1,4 +1,9 @@
-export type V2DataType = 'traffic' | 'performance' | 'errors' | 'captcha'
+export type V2DataType =
+ | 'traffic'
+ | 'performance'
+ | 'errors'
+ | 'captcha'
+ | 'seo'
export type V2FilterOperator = 'is' | 'is_not' | 'contains' | 'contains_not'
@@ -94,6 +99,59 @@ export interface CaptchaSummaryData {
previous: CaptchaSummaryStats | null
}
+interface SeoMetricValues {
+ clicks: number
+ impressions: number
+ ctr: number
+ position: number
+}
+
+export interface SeoSummaryData {
+ current: SeoMetricValues
+ previous: SeoMetricValues
+ change: SeoMetricValues
+}
+
+export interface SeoStatusData {
+ connected: boolean
+ property: string | null
+}
+
+export interface SeoBrandedTrafficData {
+ branded: number
+ nonBranded: number
+}
+
+type SeoImpressionPositionBucketKey =
+ | 'pos1To3'
+ | 'pos4To10'
+ | 'pos11To20'
+ | 'pos21Plus'
+
+type SeoOrganicPositionBucketKey =
+ | 'pos1To3'
+ | 'pos4To10'
+ | 'pos11To20'
+ | 'pos21To50'
+ | 'pos51Plus'
+
+interface SeoImpressionsByPositionEntry {
+ key: SeoImpressionPositionBucketKey
+ label: string
+ impressions: number
+ percentage: number
+}
+
+type SeoOrganicPositionEntry = { date: string } & Record<
+ SeoOrganicPositionBucketKey,
+ number
+>
+
+export interface SeoPositionsData {
+ impressionsByPosition: SeoImpressionsByPositionEntry[]
+ organicPositions: SeoOrganicPositionEntry[]
+}
+
export interface CustomEventRow {
event: string
count: number
diff --git a/web/app/hooks/useAnalyticsProxy.ts b/web/app/hooks/useAnalyticsProxy.ts
index d0686d195..dd0b01f25 100644
--- a/web/app/hooks/useAnalyticsProxy.ts
+++ b/web/app/hooks/useAnalyticsProxy.ts
@@ -1,4 +1,4 @@
-import { useCallback, useRef, useState } from 'react'
+import { useCallback, useState } from 'react'
import type {
SessionReplaysResponse,
@@ -18,7 +18,6 @@ import type {
BotProtectionStats,
BotProtectionPeriod,
JourneysResponse,
- GSCDashboardResponse,
RevenueStatus,
RevenueDataResponse,
OverallObject,
@@ -658,59 +657,6 @@ export function useJourneysProxy() {
return { fetchJourneys, data, error, isLoading }
}
-export function useGSCDashboardProxy() {
- const [data, setData] = useState<GSCDashboardResponse | null>(null)
- const [error, setError] = useState<string | null>(null)
- const [isLoading, setIsLoading] = useState(false)
- const requestIdRef = useRef(0)
-
- const fetchDashboard = useCallback(
- async (projectId: string, params: ClientAnalyticsParams = {}) => {
- const requestId = requestIdRef.current + 1
- requestIdRef.current = requestId
- setIsLoading(true)
- setError(null)
-
- try {
- const result = await postAnalytics<GSCDashboardResponse>({
- action: 'getGSCDashboard',
- projectId,
- params,
- })
-
- if (requestId !== requestIdRef.current) {
- return result.data
- }
-
- if (result.data) {
- setData(result.data)
- }
- setError(result.error)
- return result.data
- } catch (err) {
- if (requestId === requestIdRef.current) {
- setError(err instanceof Error ? err.message : 'Unknown error')
- }
- return null
- } finally {
- if (requestId === requestIdRef.current) {
- setIsLoading(false)
- }
- }
- },
- [],
- )
-
- const resetData = useCallback(() => {
- requestIdRef.current += 1
- setData(null)
- setError(null)
- setIsLoading(false)
- }, [])
-
- return { fetchDashboard, data, error, isLoading, resetData }
-}
-
export function useRevenueProxy() {
const [statusData, setStatusData] = useState<RevenueStatus | null>(null)
const [revenueData, setRevenueData] = useState<RevenueDataResponse | null>(
diff --git a/web/app/hooks/v2/useV2Queries.ts b/web/app/hooks/v2/useV2Queries.ts
index c54f09d6e..fe3113a8f 100644
--- a/web/app/hooks/v2/useV2Queries.ts
+++ b/web/app/hooks/v2/useV2Queries.ts
@@ -98,6 +98,9 @@ interface TimeseriesOpts {
mode?: 'periodical' | 'cumulative'
measure?: string
enabled?: boolean
+ // Overrides the bucket from the URL, for tabs whose data source supports a
+ // narrower set of buckets than the project view offers.
+ timeBucket?: string
}
export const useTimeseriesQuery = (
@@ -108,7 +111,7 @@ export const useTimeseriesQuery = (
const { timeBucket } = useViewProjectContext()
const params = {
...common,
- timeBucket: timeBucket || undefined,
+ timeBucket: opts.timeBucket || timeBucket || undefined,
metrics: opts.metrics,
mode: opts.mode,
measure: opts.measure,
@@ -132,7 +135,7 @@ export const useCompareTimeseriesQuery = (
const params = compare
? {
...compareOverride(common, compare),
- timeBucket: timeBucket || undefined,
+ timeBucket: opts.timeBucket || timeBucket || undefined,
metrics: opts.metrics,
mode: opts.mode,
measure: opts.measure,
@@ -213,8 +216,15 @@ export const useBreakdownDetailsQuery = (
),
initialPageParam: 0,
getNextPageParam: (lastPage, pages) => {
- const total = lastPage.meta.total ?? 0
const loaded = pages.reduce((acc, page) => acc + page.data.length, 0)
+ const total = lastPage.meta.total
+
+ // Search Console reports no row count, so fall back to treating a full
+ // page as a hint that another one may follow.
+ if (total === undefined || total === null) {
+ return lastPage.data.length === DETAILS_PAGE_SIZE ? loaded : undefined
+ }
+
return loaded < total ? loaded : undefined
},
placeholderData: keepPreviousData,
@@ -222,6 +232,43 @@ export const useBreakdownDetailsQuery = (
})
}
+export const useSeoStatusQuery = () => {
+ const { id: pid } = useCurrentProject()
+
+ return useQuery({
+ queryKey: ['v2', pid, 'seo', 'status'],
+ queryFn: ({ signal }) => v2.getSeoStatus(pid, signal),
+ placeholderData: keepPreviousData,
+ })
+}
+
+export const useSeoBrandedTrafficQuery = (opts: { enabled?: boolean } = {}) => {
+ const { pid, common } = useV2CommonParams('seo')
+
+ return useQuery({
+ queryKey: ['v2', pid, 'seo', 'branded-traffic', common],
+ queryFn: ({ signal }) => v2.getSeoBrandedTraffic(pid, common, signal),
+ placeholderData: keepPreviousData,
+ enabled: opts.enabled,
+ })
+}
+
+/**
+ * Impressions-by-position and organic positions come out of a single Search
+ * Console rollup, so both panels share one query rather than paying for it
+ * twice.
+ */
+export const useSeoPositionsQuery = (opts: { enabled?: boolean } = {}) => {
+ const { pid, common } = useV2CommonParams('seo')
+
+ return useQuery({
+ queryKey: ['v2', pid, 'seo', 'positions', common],
+ queryFn: ({ signal }) => v2.getSeoPositions(pid, common, signal),
+ placeholderData: keepPreviousData,
+ enabled: opts.enabled,
+ })
+}
+
export const useCustomEventsQuery = (
opts: { limit?: number; enabled?: boolean } = {},
) => {
diff --git a/web/app/lib/v2Dimensions.ts b/web/app/lib/v2Dimensions.ts
index d9a1a5d25..797759589 100644
--- a/web/app/lib/v2Dimensions.ts
+++ b/web/app/lib/v2Dimensions.ts
@@ -26,6 +26,9 @@ export const V1_TO_V2_DIMENSION: Record<string, string> = {
entryPage: 'entry_page',
exitPage: 'exit_page',
ev: 'event',
+ // The SEO tab's keyword filter predates v2, which names the dimension after
+ // Search Console's own 'query'.
+ keywords: 'query',
}
export const KEYED_DIMENSIONS = ['event_metadata', 'page_property'] as const
@@ -115,11 +118,14 @@ const CAPTCHA_DIMENSIONS = [
'solve_time',
]
+const SEO_DIMENSIONS = ['query', 'page', 'country', 'device']
+
export const VALID_DIMENSIONS_BY_TYPE: Record<V2DataType, string[]> = {
traffic: TRAFFIC_DIMENSIONS,
performance: PERFORMANCE_DIMENSIONS,
errors: ERROR_DIMENSIONS,
captcha: CAPTCHA_DIMENSIONS,
+ seo: SEO_DIMENSIONS,
}
export const ALL_VALID_DIMENSIONS = Array.from(
@@ -128,5 +134,6 @@ export const ALL_VALID_DIMENSIONS = Array.from(
...PERFORMANCE_DIMENSIONS,
...ERROR_DIMENSIONS,
...CAPTCHA_DIMENSIONS,
+ ...SEO_DIMENSIONS,
]),
)
diff --git a/web/app/pages/Project/View/Panels.tsx b/web/app/pages/Project/View/Panels.tsx
index 8c73d5199..cf236fbdd 100644
--- a/web/app/pages/Project/View/Panels.tsx
+++ b/web/app/pages/Project/View/Panels.tsx
@@ -1785,7 +1785,7 @@ const FilterWrapper = ({ children, as, to, ...props }: FilterWrapperProps) => {
return <div {...props}>{children}</div>
}
-interface PanelProps {
+export interface PanelProps {
name: string
data: Entry[]
rowMapper?: (row: any) => React.ReactNode
diff --git a/web/app/pages/Project/View/ViewProject.helpers.tsx b/web/app/pages/Project/View/ViewProject.helpers.tsx
index 3dfa83064..8303bea75 100644
--- a/web/app/pages/Project/View/ViewProject.helpers.tsx
+++ b/web/app/pages/Project/View/ViewProject.helpers.tsx
@@ -2346,7 +2346,7 @@ const typeNameMapping = (t: typeof i18next.t) => ({
region: t('project.mapping.rg'),
city: t('project.mapping.ct'),
page: t('project.mapping.pg'),
- keywords: t('project.seo.topQueries'),
+ query: t('project.seo.query'),
entry_page: t('project.entryPages'),
exit_page: t('project.exitPages'),
locale: t('project.mapping.lc'),
diff --git a/web/app/pages/Project/View/ViewProject.tsx b/web/app/pages/Project/View/ViewProject.tsx
index b7ebf609b..451d2c791 100644
--- a/web/app/pages/Project/View/ViewProject.tsx
+++ b/web/app/pages/Project/View/ViewProject.tsx
@@ -197,7 +197,6 @@ interface RefreshTriggersContextType {
featureFlagsRefreshTrigger: number
journeysRefreshTrigger: number
replaysRefreshTrigger: number
- seoRefreshTrigger: number
}
const defaultViewProjectContext: ViewProjectContextType = {
@@ -260,7 +259,6 @@ const defaultRefreshTriggersContext: RefreshTriggersContextType = {
featureFlagsRefreshTrigger: 0,
journeysRefreshTrigger: 0,
replaysRefreshTrigger: 0,
- seoRefreshTrigger: 0,
}
const ViewProjectContext = createContext<ViewProjectContextType>(
@@ -346,7 +344,6 @@ const ViewProjectContent = () => {
useState(0)
const [journeysRefreshTrigger, setJourneysRefreshTrigger] = useState(0)
const [replaysRefreshTrigger, setReplaysRefreshTrigger] = useState(0)
- const [seoRefreshTrigger, setSeoRefreshTrigger] = useState(0)
const customMetrics = useMemo<ProjectViewCustomEvent[]>(() => {
const raw = searchParams.get('metrics')
if (!raw) return []
@@ -893,6 +890,7 @@ const ViewProjectContent = () => {
PROJECT_TABS.funnels,
PROJECT_TABS.profiles,
PROJECT_TABS.captcha,
+ PROJECT_TABS.seo,
]),
[],
)
@@ -932,12 +930,6 @@ const ViewProjectContent = () => {
setReplaysRefreshTrigger((prev) => prev + 1)
return
}
-
- if (activeTab === PROJECT_TABS.seo) {
- await queryClient.invalidateQueries({ queryKey: ['v2', id] })
- setSeoRefreshTrigger((prev) => prev + 1)
- return
- }
},
[authLoading, dataLoading, activeTab, queryClient, id, V2_TABS],
)
@@ -1276,7 +1268,6 @@ const ViewProjectContent = () => {
featureFlagsRefreshTrigger,
journeysRefreshTrigger,
replaysRefreshTrigger,
- seoRefreshTrigger,
}),
[
goalsRefreshTrigger,
@@ -1284,7 +1275,6 @@ const ViewProjectContent = () => {
featureFlagsRefreshTrigger,
journeysRefreshTrigger,
replaysRefreshTrigger,
- seoRefreshTrigger,
],
)
diff --git a/web/app/pages/Project/View/v2/BreakdownPanel.tsx b/web/app/pages/Project/View/v2/BreakdownPanel.tsx
index 4b94cdbc1..d4f1f2069 100644
--- a/web/app/pages/Project/View/v2/BreakdownPanel.tsx
+++ b/web/app/pages/Project/View/v2/BreakdownPanel.tsx
@@ -12,7 +12,7 @@ import Button from '~/ui/Button'
import { Text } from '~/ui/Text'
import { getItem, setItem } from '~/utils/localstorage'
-import { Panel, PanelContainer } from '../Panels'
+import { Panel, PanelContainer, type PanelProps } from '../Panels'
import { groupVersionRows, mapBreakdownRows } from './adapters'
export interface BreakdownSubTab {
@@ -33,6 +33,7 @@ interface BreakdownPanelProps {
primaryMetric?: string
metrics?: string[]
measure?: string
+ sort?: string
rowMapper?: (entry: Entry, subTabId: string) => React.ReactNode
valueMapper?: (value: number, subTabId: string) => number
transformEntries?: (entries: Entry[], subTabId: string) => Entry[]
@@ -50,6 +51,11 @@ interface BreakdownPanelProps {
valuesHeaderName?: string
highlightColour?: 'blue' | 'red' | 'orange'
onActiveSubTabChange?: (subTabId: string) => void
+ detailsExtraColumns?: PanelProps['detailsExtraColumns']
+ rowTooltipRenderer?: PanelProps['rowTooltipRenderer']
+ rowTooltipFollowCursor?: boolean
+ hidePercentageInDetails?: boolean
+ disableRowClick?: boolean
}
const subTabStorageKey = (dataType: string, panelId: string) =>
@@ -64,6 +70,7 @@ export const BreakdownPanel = ({
primaryMetric = 'visitors',
metrics,
measure,
+ sort,
rowMapper,
valueMapper,
transformEntries,
@@ -73,6 +80,11 @@ export const BreakdownPanel = ({
valuesHeaderName,
highlightColour,
onActiveSubTabChange,
+ detailsExtraColumns,
+ rowTooltipRenderer,
+ rowTooltipFollowCursor,
+ hidePercentageInDetails,
+ disableRowClick,
}: BreakdownPanelProps) => {
const { t } = useTranslation('common')
const { getFilterLink: getFilterLinkContext } = useViewProjectContext()
@@ -99,11 +111,13 @@ export const BreakdownPanel = ({
const isSentinel = !activeSubTab.dimension
+ const resolvedSort = sort ?? `${primaryMetric}:desc`
+
const query = useBreakdownDetailsQuery(dataType, {
dimension: activeSubTab.dimension || '',
metrics,
measure,
- sort: `${primaryMetric}:desc`,
+ sort: resolvedSort,
enabled: hasBeenInView && !isSentinel,
})
@@ -111,7 +125,7 @@ export const BreakdownPanel = ({
dimension: activeSubTab.versionsDimension || '',
metrics,
measure,
- sort: `${primaryMetric}:desc`,
+ sort: resolvedSort,
enabled: hasBeenInView && Boolean(activeSubTab.versionsDimension),
})
@@ -119,9 +133,10 @@ export const BreakdownPanel = ({
const mapped = mapBreakdownRows(
query.data?.pages.flatMap((page) => page.data),
primaryMetric,
+ metrics,
)
return transformEntries ? transformEntries(mapped, activeSubTabId) : mapped
- }, [query.data, primaryMetric, transformEntries, activeSubTabId])
+ }, [query.data, primaryMetric, metrics, transformEntries, activeSubTabId])
const versionData = useMemo(() => {
if (!activeSubTab.versionsDimension || !versionsQuery.data) {
@@ -224,6 +239,11 @@ export const BreakdownPanel = ({
}
valuesHeaderName={valuesHeaderName}
highlightColour={highlightColour}
+ detailsExtraColumns={detailsExtraColumns}
+ rowTooltipRenderer={rowTooltipRenderer}
+ rowTooltipFollowCursor={rowTooltipFollowCursor}
+ hidePercentageInDetails={hidePercentageInDetails}
+ disableRowClick={disableRowClick}
dataLoading={query.isFetching && !query.isFetchingNextPage}
isRefetching={
query.isFetching && !query.isLoading && !query.isFetchingNextPage
diff --git a/web/app/pages/Project/View/v2/adapters.ts b/web/app/pages/Project/View/v2/adapters.ts
index a75701b0b..a3a890b1e 100644
--- a/web/app/pages/Project/View/v2/adapters.ts
+++ b/web/app/pages/Project/View/v2/adapters.ts
@@ -11,6 +11,9 @@ import { OverallObject } from '~/lib/models/Project'
export const mapBreakdownRows = (
rows: BreakdownRow[] | undefined,
primaryMetric = 'visitors',
+ // Metrics beyond the primary one are copied onto the entry so panels can show
+ // them in extra columns or row tooltips (the SEO panels lean on this).
+ extraMetrics?: string[],
): Entry[] => {
if (!rows) return []
@@ -19,6 +22,11 @@ export const mapBreakdownRows = (
count: Number(row[primaryMetric] ?? 0),
...(typeof row.country === 'string' ? { cc: row.country } : {}),
...(typeof row.region_code === 'string' ? { rgc: row.region_code } : {}),
+ ...Object.fromEntries(
+ (extraMetrics ?? [])
+ .filter((metric) => metric !== primaryMetric)
+ .map((metric) => [metric, Number(row[metric] ?? 0)]),
+ ),
}))
}
diff --git a/web/app/pages/Project/tabs/SEO/SEOView.tsx b/web/app/pages/Project/tabs/SEO/SEOView.tsx
index 856fa3387..a5a38ac27 100644
--- a/web/app/pages/Project/tabs/SEO/SEOView.tsx
+++ b/web/app/pages/Project/tabs/SEO/SEOView.tsx
@@ -1,5 +1,5 @@
import {
- ArrowClockwiseIcon,
+ ArrowsClockwiseIcon,
EyeIcon,
InfoIcon,
LinkIcon,
@@ -14,55 +14,63 @@ import {
import dayjs from 'dayjs'
import _isEmpty from 'lodash/isEmpty'
import _round from 'lodash/round'
-import React, { useEffect, useCallback, useMemo, useRef, useState } from 'react'
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
import { Trans, useTranslation } from 'react-i18next'
import { Link } from '~/ui/Link'
import { useSearchParams } from 'react-router'
-import { useGSCDashboardProxy } from '~/hooks/useAnalyticsProxy'
-import { useBreakdownQuery } from '~/hooks/v2/useV2Queries'
-import { mapBreakdownRows } from '~/pages/Project/View/v2/adapters'
import { useAnnotations } from '~/hooks/useAnnotations'
+import { useInViewOnce } from '~/hooks/useInViewOnce'
+import {
+ useBreakdownQuery,
+ useCompareSummaryQuery,
+ useCompareTimeseriesQuery,
+ useSeoBrandedTrafficQuery,
+ useSeoPositionsQuery,
+ useSeoStatusQuery,
+ useSummaryQuery,
+ useTimeseriesQuery,
+} from '~/hooks/v2/useV2Queries'
import { DOCS_URL } from '~/lib/constants'
import type { TimeBucket } from '~/lib/constants'
import type { Entry } from '~/lib/models/Entry'
-import BillboardChart from '~/ui/BillboardChart'
import AnnotationModal from '~/modals/AnnotationModal'
import { ChartContextMenu } from '~/pages/Project/View/components/ChartContextMenu'
import DashboardHeader from '~/pages/Project/View/components/DashboardHeader'
-import { MainChart } from '~/pages/Project/View/components/MainChart'
import Filters from '~/pages/Project/View/components/Filters'
+import { MainChart } from '~/pages/Project/View/components/MainChart'
import ProjectViewHeaderActions from '~/pages/Project/View/components/ProjectViewHeaderActions'
import TabErrorBoundary from '~/pages/Project/View/components/TabErrorBoundary'
+import CCRow from '~/pages/Project/View/components/CCRow'
import {
- Panel,
PanelContainer,
PanelEmptyState,
PanelLoadingState,
} from '~/pages/Project/View/Panels'
import {
- useViewProjectContext,
- useRefreshTriggers,
-} from '~/pages/Project/View/ViewProject'
+ BreakdownPanel,
+ type BreakdownSubTab,
+} from '~/pages/Project/View/v2/BreakdownPanel'
+import { mapBreakdownRows } from '~/pages/Project/View/v2/adapters'
+import { useViewProjectContext } from '~/pages/Project/View/ViewProject'
import {
noRegionPeriods,
panelIconMapping,
getDeviceRowMapper,
} from '~/pages/Project/View/ViewProject.helpers'
import { MetricCard } from '~/pages/Project/tabs/Traffic/MetricCards'
-import { CompactNumberFlow, PercentFlow } from '~/ui/NumberFlow'
import RefRow from '~/pages/Project/tabs/Traffic/RefRow'
-import CCRow from '~/pages/Project/View/components/CCRow'
import { useCurrentProject } from '~/providers/CurrentProjectProvider'
import { useTheme } from '~/providers/ThemeProvider'
+import BillboardChart from '~/ui/BillboardChart'
+import Button from '~/ui/Button'
import Checkbox from '~/ui/Checkbox'
import Dropdown from '~/ui/Dropdown'
import Loader from '~/ui/Loader'
-import LoadingBar from '~/ui/LoadingBar'
+import { CompactNumberFlow, PercentFlow } from '~/ui/NumberFlow'
import { Text } from '~/ui/Text'
import Tooltip from '~/ui/Tooltip'
import { nFormatter } from '~/utils/generic'
-import countries from '~/utils/isoCountries'
import { getSearchEngineReferrals, getAIReferrals } from '~/utils/referrers'
import routes from '~/utils/routes'
@@ -70,8 +78,8 @@ import CompactReferralPanel from './CompactReferralPanel'
import {
SEO_METRICS,
type SEOMetricKey,
- aggregateDateSeries,
hasOrganicPositionData,
+ seoTimeseriesToDateSeries,
} from './seo-utils'
import type { QuadrantData } from './seo-chart-options'
import {
@@ -89,7 +97,16 @@ interface SEOViewProps {
const SEO_DOCS_URL = `${DOCS_URL}/analytics-dashboard/seo`
-const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
+// Every metric the seo endpoints expose. Panels ask for all four so impressions,
+// CTR and position are available for the extra columns and row tooltips.
+const SEO_BREAKDOWN_METRICS = ['clicks', 'impressions', 'ctr', 'position']
+
+// Search Console orders rows by clicks descending and offers no sort control.
+const SEO_SORT = 'clicks:desc'
+
+const QUADRANT_QUERY_LIMIT = 50
+
+const SEOViewInner = ({ tnMapping }: SEOViewProps) => {
const {
t,
i18n: { language },
@@ -98,7 +115,6 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
const { id, allowedToManage } = useCurrentProject()
const {
period,
- timezone,
timeFormat,
timeBucket,
periodPairs,
@@ -106,15 +122,6 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
getFilterLink,
isActiveCompare,
} = useViewProjectContext()
- const { seoRefreshTrigger } = useRefreshTriggers()
- const { fetchDashboard, data, error, isLoading } = useGSCDashboardProxy()
- const {
- fetchDashboard: fetchCompareDashboard,
- data: compareData,
- error: compareError,
- isLoading: isCompareLoading,
- resetData: resetCompareData,
- } = useGSCDashboardProxy()
const [searchParams, setSearchParams] = useSearchParams()
const {
annotations,
@@ -196,6 +203,70 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
urlTimeBucket,
])
+ const statusQuery = useSeoStatusQuery()
+ const status = statusQuery.data?.data
+ const isConnected = Boolean(status?.connected && status?.property)
+
+ // The expensive rollups and the quadrant only fetch once scrolled to, so an
+ // SEO page load costs Search Console nothing it does not display. The panels
+ // below gate their spinner on isPending rather than isLoading: a query that
+ // is disabled (not yet scrolled to) or paused (offline) is pending but not
+ // fetching, and isLoading would call that "no data" instead of "not yet".
+ const { ref: brandedRef, hasBeenInView: brandedInView } = useInViewOnce()
+ const { ref: positionsRef, hasBeenInView: positionsInView } = useInViewOnce()
+ const { ref: quadrantRef, hasBeenInView: quadrantInView } = useInViewOnce()
+
+ const summaryQuery = useSummaryQuery('seo', { enabled: isConnected })
+ const compareSummaryQuery = useCompareSummaryQuery('seo', {
+ enabled: isConnected,
+ })
+ const timeseriesQuery = useTimeseriesQuery('seo', {
+ timeBucket: seoTimeBucket,
+ enabled: isConnected,
+ })
+ const compareTimeseriesQuery = useCompareTimeseriesQuery('seo', {
+ timeBucket: seoTimeBucket,
+ enabled: isConnected,
+ })
+ const brandedQuery = useSeoBrandedTrafficQuery({
+ enabled: isConnected && brandedInView,
+ })
+ const positionsQuery = useSeoPositionsQuery({
+ enabled: isConnected && positionsInView,
+ })
+ const quadrantQuery = useBreakdownQuery('seo', {
+ dimension: 'query',
+ metrics: SEO_BREAKDOWN_METRICS,
+ limit: QUADRANT_QUERY_LIMIT,
+ sort: SEO_SORT,
+ enabled: isConnected && quadrantInView,
+ })
+
+ const referrerQuery = useBreakdownQuery('traffic', {
+ dimension: 'referrer',
+ limit: 100,
+ sort: 'visitors:desc',
+ })
+
+ const refEntries: Entry[] = useMemo(
+ () => mapBreakdownRows(referrerQuery.data?.data),
+ [referrerQuery.data],
+ )
+
+ const searchEngineEntries = useMemo(
+ () => getSearchEngineReferrals(refEntries),
+ [refEntries],
+ )
+ const aiReferralEntries = useMemo(
+ () => getAIReferrals(refEntries),
+ [refEntries],
+ )
+
+ const refRowMapper = useCallback(
+ ({ name: entryName }: any) => <RefRow rowName={entryName} />,
+ [],
+ )
+
const metricItems = useMemo(
() => [
{
@@ -229,144 +300,28 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
}))
}, [])
- const referrerQuery = useBreakdownQuery('traffic', {
- dimension: 'referrer',
- limit: 100,
- sort: 'visitors:desc',
- })
-
- const refEntries: Entry[] = useMemo(
- () => mapBreakdownRows(referrerQuery.data?.data),
- [referrerQuery.data],
- )
-
- const searchEngineEntries = useMemo(
- () => getSearchEngineReferrals(refEntries),
- [refEntries],
- )
- const aiReferralEntries = useMemo(
- () => getAIReferrals(refEntries),
- [refEntries],
- )
+ const summary = summaryQuery.data?.data.current
+ const comparisonSummary = isActiveCompare
+ ? compareSummaryQuery.data?.data.current
+ : summaryQuery.data?.data.previous
- const refRowMapper = useCallback(
- ({ name: entryName }: any) => <RefRow rowName={entryName} />,
- [],
+ const series = useMemo(
+ () => seoTimeseriesToDateSeries(timeseriesQuery.data?.data, seoTimeBucket),
+ [timeseriesQuery.data, seoTimeBucket],
)
- const noopFilterLink = useCallback(() => '#', [])
- const gscLoading = isLoading || isCompareLoading
- const gscError = error || compareError
-
- // No cached response to fall back on — panels show spinners rather than
- // claiming they have no data.
- const isSEOLoading = gscLoading && !data
-
- const [isManualRefreshing, setIsManualRefreshing] = useState(false)
-
- const prevTrigger = useRef(seoRefreshTrigger)
-
- const from = searchParams.get('from') || undefined
- const to = searchParams.get('to') || undefined
- const compareEnabled = searchParams.get('compare') === 'true'
- const compareFrom = searchParams.get('compareFrom') || undefined
- const compareTo = searchParams.get('compareTo') || undefined
-
- const loadData = useCallback(async () => {
- const params = {
- period,
- from,
- to,
- timezone,
- timeBucket: seoTimeBucket,
- filters,
- }
-
- const currentPromise = fetchDashboard(projectId, params)
-
- if (isActiveCompare && compareEnabled && compareFrom && compareTo) {
- resetCompareData()
- await Promise.all([
- currentPromise,
- fetchCompareDashboard(projectId, {
- ...params,
- period: 'custom',
- from: compareFrom,
- to: compareTo,
- }),
- ])
- return
- }
-
- resetCompareData()
- await currentPromise
- }, [
- fetchDashboard,
- fetchCompareDashboard,
- resetCompareData,
- projectId,
- period,
- from,
- to,
- compareEnabled,
- compareFrom,
- compareTo,
- timezone,
- seoTimeBucket,
- filters,
- isActiveCompare,
- ])
-
- useEffect(() => {
- loadData()
- }, [loadData])
-
- useEffect(() => {
- if (seoRefreshTrigger !== prevTrigger.current) {
- prevTrigger.current = seoRefreshTrigger
- loadData()
- }
- }, [seoRefreshTrigger, loadData])
-
- const handleManualRefresh = useCallback(async () => {
- if (isManualRefreshing) return
- setIsManualRefreshing(true)
- try {
- await loadData()
- } finally {
- setIsManualRefreshing(false)
- }
- }, [isManualRefreshing, loadData])
-
- const manualRefreshButton = useMemo(
- () => (
- <button
- type='button'
- title={t('project.refreshStats')}
- onClick={handleManualRefresh}
- className='relative rounded-md border border-transparent p-2 transition-all ring-inset hover:border-gray-300 hover:bg-white focus:z-10 focus:ring-1 focus:ring-slate-900 focus:outline-hidden hover:dark:border-slate-700/80 dark:hover:bg-slate-900 dark:focus:ring-slate-300'
- >
- <ArrowClockwiseIcon
- className={`h-5 w-5 text-gray-700 dark:text-gray-50 ${isManualRefreshing ? 'animate-spin' : ''}`}
- />
- </button>
- ),
- [t, handleManualRefresh, isManualRefreshing],
- )
-
- const aggregatedSeries = useMemo(
- () => aggregateDateSeries(data?.dateSeries || [], seoTimeBucket),
- [data?.dateSeries, seoTimeBucket],
- )
-
- const aggregatedCompareSeries = useMemo(
- () => aggregateDateSeries(compareData?.dateSeries || [], seoTimeBucket),
- [compareData?.dateSeries, seoTimeBucket],
+ const compareSeries = useMemo(
+ () =>
+ seoTimeseriesToDateSeries(
+ compareTimeseriesQuery.data?.data,
+ seoTimeBucket,
+ ),
+ [compareTimeseriesQuery.data, seoTimeBucket],
)
const chartXAxisData = useMemo(
- () => aggregatedSeries.map((entry) => entry.date),
- [aggregatedSeries],
+ () => series.map((entry) => entry.date),
+ [series],
)
const filteredAnnotations = useMemo(() => {
@@ -386,82 +341,13 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
})
}, [annotations, chartXAxisData])
- const topPagesAsEntries: Entry[] = useMemo(
- () =>
- (data?.topPages || []).map(
- (p) =>
- ({
- name: p.page,
- count: p.clicks,
- impressions: p.impressions,
- ctr: p.ctr,
- position: p.position,
- }) as Entry & { impressions: number; ctr: number; position: number },
- ),
- [data?.topPages],
- )
-
- const topQueriesAsEntries: (Entry & {
- impressions: number
- ctr: number
- position: number
- })[] = useMemo(
- () =>
- (data?.topQueries || []).map(
- (q) =>
- ({
- name: q.name,
- count: q.count,
- impressions: q.impressions,
- ctr: q.ctr,
- position: q.position,
- }) as Entry & { impressions: number; ctr: number; position: number },
- ),
- [data?.topQueries],
- )
-
- const topCountriesAsEntries: Entry[] = useMemo(
- () =>
- (data?.topCountries || []).map((c) => {
- const alpha2 =
- countries.alpha3ToAlpha2(c.country.toUpperCase())?.toLowerCase() ||
- c.country
- return {
- name: alpha2,
- count: c.clicks,
- impressions: c.impressions,
- ctr: c.ctr,
- position: c.position,
- } as Entry & { impressions: number; ctr: number; position: number }
- }),
- [data?.topCountries],
- )
+ const isBrandedTrafficSkipped = brandedQuery.data?.meta.skipped === true
- const topDevicesAsEntries: Entry[] = useMemo(
- () =>
- (data?.topDevices || []).map(
- (d) =>
- ({
- name: d.device,
- count: d.clicks,
- impressions: d.impressions,
- ctr: d.ctr,
- position: d.position,
- }) as Entry & { impressions: number; ctr: number; position: number },
- ),
- [data?.topDevices],
+ const brandedTraffic = useMemo(
+ () => brandedQuery.data?.data ?? { branded: 0, nonBranded: 0 },
+ [brandedQuery.data],
)
- const isBrandedTrafficSkipped = data?.brandedTraffic?.skipped === true
-
- const brandedTraffic = useMemo(() => {
- if (!data?.brandedTraffic || data.brandedTraffic.skipped) {
- return { branded: 0, nonBranded: 0 }
- }
-
- return data.brandedTraffic
- }, [data?.brandedTraffic])
-
const donutChartOptions = useMemo(
() =>
buildDonutChartOptions(
@@ -473,21 +359,18 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
[brandedTraffic, t, theme],
)
+ const isPositionAnalyticsSkipped = positionsQuery.data?.meta.skipped === true
+
const impressionsByPosition = useMemo(
- () => data?.impressionsByPosition || [],
- [data?.impressionsByPosition],
+ () => positionsQuery.data?.data?.impressionsByPosition ?? [],
+ [positionsQuery.data],
)
const organicPositions = useMemo(
- () => data?.organicPositions || [],
- [data?.organicPositions],
+ () => positionsQuery.data?.data?.organicPositions ?? [],
+ [positionsQuery.data],
)
- const isPositionAnalyticsSkipped =
- data?.positionAnalyticsSkipped === true ||
- data?.impressionsByPosition === null ||
- data?.organicPositions === null
-
const hasImpressionsByPositionData = useMemo(
() => impressionsByPosition.some((bucket) => bucket.impressions > 0),
[impressionsByPosition],
@@ -514,59 +397,63 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
[language],
)
- const deviceRowMapper = useMemo(
- () => getDeviceRowMapper('dv', theme, t),
+ const deviceRowMapper = useCallback(
+ (entry: Entry) => {
+ const mapper = getDeviceRowMapper('dv', theme, t) as
+ | ((entry: Entry) => React.ReactNode)
+ | undefined
+ return mapper ? mapper(entry) : entry.name
+ },
[theme, t],
)
const anyMetricActive = Object.values(activeMetrics).some(Boolean)
const quadrantData: QuadrantData | null = useMemo(() => {
- if (!topQueriesAsEntries.length) return null
- const positions = topQueriesAsEntries.map((q) => q.position)
- const ctrs = topQueriesAsEntries.map((q) => q.ctr)
- const impressions = topQueriesAsEntries.map((q) => q.impressions)
- const names = topQueriesAsEntries.map((q) => q.name ?? '')
+ const entries = mapBreakdownRows(
+ quadrantQuery.data?.data,
+ 'clicks',
+ SEO_BREAKDOWN_METRICS,
+ ) as (Entry & { impressions: number; ctr: number; position: number })[]
+
+ if (!entries.length) return null
+
+ const positions = entries.map((q) => q.position)
+ const ctrs = entries.map((q) => q.ctr)
+ const impressions = entries.map((q) => q.impressions)
+ const names = entries.map((q) => q.name ?? '')
const maxImp = Math.max(...impressions) || 1
const minImp = Math.min(...impressions) || 0
return { positions, ctrs, impressions, names, maxImp, minImp }
- }, [topQueriesAsEntries])
+ }, [quadrantQuery.data])
const quadrantChartOptions = useMemo(() => {
if (!quadrantData) return {}
- const avgCtr = data?.summary?.ctr ?? 5
- const avgPos = data?.summary?.position ?? 10
+ const avgCtr = summary?.ctr ?? 5
+ const avgPos = summary?.position ?? 10
return buildQuadrantChartOptions(quadrantData, avgCtr, avgPos, theme, t)
- }, [quadrantData, data?.summary, theme, t])
-
- const comparisonSummary =
- isActiveCompare && compareEnabled
- ? compareData?.summary
- : data?.previousSummary
+ }, [quadrantData, summary, theme, t])
const chartOptions = useMemo(
() =>
buildMainChartOptions(
- aggregatedSeries,
+ series,
activeMetrics,
seoTimeBucket,
t,
!noRegionPeriods.includes(period),
filteredAnnotations,
- isActiveCompare && compareEnabled && aggregatedCompareSeries.length
- ? aggregatedCompareSeries
- : undefined,
+ isActiveCompare && compareSeries.length ? compareSeries : undefined,
),
[
- aggregatedSeries,
+ series,
activeMetrics,
seoTimeBucket,
t,
isActiveCompare,
- compareEnabled,
- aggregatedCompareSeries,
+ compareSeries,
period,
filteredAnnotations,
],
@@ -706,46 +593,75 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
[t],
)
- if (gscError && !data) {
+ const pagesSubTabs = useMemo<BreakdownSubTab[]>(
+ () => [{ id: 'page', label: t('project.seo.page'), dimension: 'page' }],
+ [t],
+ )
+
+ const queriesSubTabs = useMemo<BreakdownSubTab[]>(
+ () => [{ id: 'query', label: t('project.seo.query'), dimension: 'query' }],
+ [t],
+ )
+
+ const countriesSubTabs = useMemo<BreakdownSubTab[]>(
+ () => [
+ { id: 'country', label: t('project.mapping.cc'), dimension: 'country' },
+ ],
+ [t],
+ )
+
+ const devicesSubTabs = useMemo<BreakdownSubTab[]>(
+ () => [
+ { id: 'device', label: t('project.mapping.dv'), dimension: 'device' },
+ ],
+ [t],
+ )
+
+ const header = (
+ <DashboardHeader
+ showSearchButton={false}
+ rightContent={<ProjectViewHeaderActions tnMapping={tnMapping} />}
+ timeBucketSelectorItems={seoPeriodPairs}
+ />
+ )
+
+ if (statusQuery.isLoading) {
return (
<>
- <DashboardHeader
- showSearchButton={false}
- showRefreshButton={false}
- rightContent={
- <ProjectViewHeaderActions
- tnMapping={tnMapping}
- extraActions={manualRefreshButton}
- />
- }
- timeBucketSelectorItems={seoPeriodPairs}
- />
+ {header}
+ <div className='flex min-h-[400px] items-center justify-center'>
+ <Loader />
+ </div>
+ </>
+ )
+ }
+
+ if (statusQuery.isError) {
+ return (
+ <>
+ {header}
<div className='mx-auto flex min-h-[400px] max-w-xl flex-col items-center justify-center px-4 text-center'>
<Text as='h3' size='lg' weight='medium'>
{t('apiNotifications.somethingWentWrong')}
</Text>
- <Text as='p' size='sm' colour='secondary' className='mt-2'>
- {gscError}
- </Text>
+ <Button
+ className='mt-3 gap-1.5'
+ onClick={() => statusQuery.refetch()}
+ variant='secondary'
+ size='sm'
+ >
+ <ArrowsClockwiseIcon className='size-4' />
+ {t('project.refreshStats')}
+ </Button>
</div>
</>
)
}
- if (data?.notConnected) {
+ if (!isConnected) {
return (
<>
- <DashboardHeader
- showSearchButton={false}
- showRefreshButton={false}
- rightContent={
- <ProjectViewHeaderActions
- tnMapping={tnMapping}
- extraActions={manualRefreshButton}
- />
- }
- timeBucketSelectorItems={seoPeriodPairs}
- />
+ {header}
<div className='mx-auto w-full max-w-2xl py-16 text-center'>
<div className='mx-auto mb-6 flex size-14 items-center justify-center rounded-xl bg-gray-100 dark:bg-slate-900'>
<PlugIcon
@@ -778,7 +694,7 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
}}
/>
</Text>
- {data?.noProperty ? (
+ {status?.connected && !status?.property ? (
<Text
as='p'
size='sm'
@@ -799,23 +715,15 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
)
}
+ const isHeroLoading = summaryQuery.isPending || timeseriesQuery.isPending
+ const isHeroError = summaryQuery.isError || timeseriesQuery.isError
+
return (
<>
- <DashboardHeader
- showSearchButton={false}
- showRefreshButton={false}
- rightContent={
- <ProjectViewHeaderActions
- tnMapping={tnMapping}
- extraActions={manualRefreshButton}
- />
- }
- timeBucketSelectorItems={seoPeriodPairs}
- />
+ {header}
{filters.length > 0 ? (
<Filters className='mb-3' tnMapping={tnMapping} />
) : null}
- {gscLoading && data ? <LoadingBar /> : null}
<div className='relative overflow-hidden rounded-lg border border-gray-200 bg-white p-4 dark:border-slate-800/60 dark:bg-slate-900/25'>
<div className='mb-3 flex w-full items-center justify-end gap-1 lg:absolute lg:top-2 lg:right-2 lg:mb-0 lg:w-auto lg:justify-normal'>
@@ -856,10 +764,10 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
<div className='mb-5 flex flex-wrap justify-center gap-5 lg:justify-start'>
<MetricCard
label={t('project.seo.clicks')}
- value={data?.summary?.clicks ?? 0}
+ value={summary?.clicks ?? 0}
change={
comparisonSummary
- ? (data?.summary?.clicks ?? 0) - comparisonSummary.clicks
+ ? (summary?.clicks ?? 0) - comparisonSummary.clicks
: undefined
}
goodChangeDirection='down'
@@ -873,11 +781,10 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
/>
<MetricCard
label={t('project.seo.impressions')}
- value={data?.summary?.impressions ?? 0}
+ value={summary?.impressions ?? 0}
change={
comparisonSummary
- ? (data?.summary?.impressions ?? 0) -
- comparisonSummary.impressions
+ ? (summary?.impressions ?? 0) - comparisonSummary.impressions
: undefined
}
goodChangeDirection='down'
@@ -891,10 +798,10 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
/>
<MetricCard
label={t('project.seo.avgCTR')}
- value={_round(data?.summary?.ctr ?? 0, 2)}
+ value={_round(summary?.ctr ?? 0, 2)}
change={
comparisonSummary
- ? _round((data?.summary?.ctr ?? 0) - comparisonSummary.ctr, 2)
+ ? _round((summary?.ctr ?? 0) - comparisonSummary.ctr, 2)
: undefined
}
type='percent'
@@ -909,11 +816,11 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
/>
<MetricCard
label={t('project.seo.avgPosition')}
- value={_round(data?.summary?.position ?? 0, 1)}
+ value={_round(summary?.position ?? 0, 1)}
change={
comparisonSummary
? _round(
- (data?.summary?.position ?? 0) - comparisonSummary.position,
+ (summary?.position ?? 0) - comparisonSummary.position,
1,
)
: undefined
@@ -928,12 +835,29 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
}
/>
</div>
- {isSEOLoading ? (
+ {isHeroError ? (
+ <div className='flex h-80 flex-col items-center justify-center text-center'>
+ <Text as='p' size='sm' colour='secondary'>
+ {t('apiNotifications.somethingWentWrong')}
+ </Text>
+ <Button
+ className='mt-3 gap-1.5'
+ onClick={() => {
+ summaryQuery.refetch()
+ timeseriesQuery.refetch()
+ }}
+ variant='secondary'
+ size='sm'
+ >
+ <ArrowsClockwiseIcon className='size-4' />
+ {t('project.refreshStats')}
+ </Button>
+ </div>
+ ) : isHeroLoading ? (
<div className='flex h-80 items-center justify-center'>
<Loader className='pt-0!' />
</div>
- ) : null}
- {anyMetricActive && !_isEmpty(aggregatedSeries) ? (
+ ) : anyMetricActive && !_isEmpty(series) ? (
<div
onContextMenu={(event) =>
handleChartContextMenu(event, chartXAxisData)
@@ -945,8 +869,8 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
options={chartOptions}
className='h-80 [&_svg]:overflow-visible!'
deps={[
- aggregatedSeries,
- aggregatedCompareSeries,
+ series,
+ compareSeries,
activeMetrics,
seoTimeBucket,
timeFormat,
@@ -964,24 +888,31 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
data={searchEngineEntries}
icon={panelIconMapping.referrer}
rowMapper={refRowMapper}
- isLoading={isSEOLoading}
+ isLoading={referrerQuery.isLoading}
/>
<CompactReferralPanel
title={t('project.seo.aiReferrals')}
data={aiReferralEntries}
icon={<RobotIcon className='h-5 w-5' />}
rowMapper={refRowMapper}
- isLoading={isSEOLoading}
+ isLoading={referrerQuery.isLoading}
/>
- <div className='overflow-hidden rounded-lg border border-gray-200 bg-white px-4 py-3 dark:border-slate-800/60 dark:bg-slate-900/25'>
+ <div
+ ref={brandedRef}
+ className='overflow-hidden rounded-lg border border-gray-200 bg-white px-4 py-3 dark:border-slate-800/60 dark:bg-slate-900/25'
+ >
<div className='mb-1 flex items-center gap-1 text-gray-900 dark:text-gray-50'>
<MagnifyingGlassIcon className='size-5' />
<Text size='sm' weight='semibold'>
{t('project.seo.brandedTraffic')}
</Text>
</div>
- {isSEOLoading ? (
+ {brandedQuery.isPending ? (
<PanelLoadingState />
+ ) : brandedQuery.isError ? (
+ <PanelEmptyState
+ message={t('apiNotifications.somethingWentWrong')}
+ />
) : isBrandedTrafficSkipped ? (
<PanelEmptyState message={t('project.seo.analyticsSkipped')} />
) : brandedTraffic.branded + brandedTraffic.nonBranded > 0 ? (
@@ -996,15 +927,23 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
</div>
</div>
- <div className='mt-3 grid grid-cols-1 gap-3 xl:grid-cols-[minmax(0,0.9fr)_minmax(0,1.35fr)]'>
+ <div
+ ref={positionsRef}
+ className='mt-3 grid grid-cols-1 gap-3 xl:grid-cols-[minmax(0,0.9fr)_minmax(0,1.35fr)]'
+ >
<PanelContainer
name={t('project.seo.impressionsByPosition')}
icon={<ChartBarIcon className='size-5' />}
type='impressionsByPosition'
contentClassName='relative flex min-h-[21rem] flex-col overflow-hidden'
- isLoading={isSEOLoading}
+ isLoading={positionsQuery.isPending}
+ isRefetching={positionsQuery.isFetching && !positionsQuery.isPending}
>
- {isPositionAnalyticsSkipped ? (
+ {positionsQuery.isError ? (
+ <PanelEmptyState
+ message={t('apiNotifications.somethingWentWrong')}
+ />
+ ) : isPositionAnalyticsSkipped ? (
<PanelEmptyState message={t('project.seo.analyticsSkipped')} />
) : hasImpressionsByPositionData ? (
<BillboardChart
@@ -1022,9 +961,14 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
icon={<TrendUpIcon className='size-5' />}
type='organicPositions'
contentClassName='relative flex min-h-[21rem] flex-col overflow-hidden'
- isLoading={isSEOLoading}
+ isLoading={positionsQuery.isPending}
+ isRefetching={positionsQuery.isFetching && !positionsQuery.isPending}
>
- {isPositionAnalyticsSkipped ? (
+ {positionsQuery.isError ? (
+ <PanelEmptyState
+ message={t('apiNotifications.somethingWentWrong')}
+ />
+ ) : isPositionAnalyticsSkipped ? (
<PanelEmptyState message={t('project.seo.analyticsSkipped')} />
) : hasOrganicPositions ? (
<BillboardChart
@@ -1039,41 +983,41 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
</div>
<div className='mt-3 grid grid-cols-1 gap-3 sm:grid-cols-2'>
- <Panel
+ <BreakdownPanel
+ dataType='seo'
+ panelId='pages'
name={t('project.seo.topPages')}
- data={topPagesAsEntries}
icon={panelIconMapping.page}
- id='pg'
- activeTabId='pg'
- disableRowClick={false}
+ subTabs={pagesSubTabs}
+ primaryMetric='clicks'
+ metrics={SEO_BREAKDOWN_METRICS}
+ sort={SEO_SORT}
getFilterLink={getFilterLink}
valuesHeaderName={t('project.seo.clicks')}
detailsExtraColumns={detailsExtraColumns}
hidePercentageInDetails
- dataLoading={gscLoading}
- isLoading={isSEOLoading}
rowTooltipRenderer={seoGscRowTooltip}
rowTooltipFollowCursor
/>
- <Panel
+ <BreakdownPanel
+ dataType='seo'
+ panelId='queries'
name={t('project.seo.topQueries')}
- data={topQueriesAsEntries}
icon={<MagnifyingGlassIcon className='h-5 w-5' />}
- id='keywords'
- activeTabId='keywords'
- disableRowClick={false}
+ subTabs={queriesSubTabs}
+ primaryMetric='clicks'
+ metrics={SEO_BREAKDOWN_METRICS}
+ sort={SEO_SORT}
getFilterLink={getFilterLink}
valuesHeaderName={t('project.seo.clicks')}
detailsExtraColumns={detailsExtraColumns}
hidePercentageInDetails
- dataLoading={gscLoading}
- isLoading={isSEOLoading}
rowTooltipRenderer={seoGscRowTooltip}
rowTooltipFollowCursor
/>
</div>
- <div className='mt-3'>
+ <div className='mt-3' ref={quadrantRef}>
<PanelContainer
name={t('project.seo.quadrant')}
icon={<TargetIcon className='size-5' />}
@@ -1097,10 +1041,14 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
}
contentClassName=''
>
- {isSEOLoading ? (
+ {quadrantQuery.isPending ? (
<div className='flex h-[400px] items-center justify-center'>
<Loader className='pt-0!' />
</div>
+ ) : quadrantQuery.isError ? (
+ <PanelEmptyState
+ message={t('apiNotifications.somethingWentWrong')}
+ />
) : quadrantData ? (
<BillboardChart
options={quadrantChartOptions}
@@ -1114,36 +1062,36 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
</div>
<div className='mt-3 grid grid-cols-1 gap-3 sm:grid-cols-2'>
- <Panel
+ <BreakdownPanel
+ dataType='seo'
+ panelId='location'
name={t('project.location')}
- data={topCountriesAsEntries}
icon={<MapPinIcon className='h-5 w-5' />}
- id='country'
- activeTabId='cc'
- disableRowClick
- getFilterLink={noopFilterLink}
+ subTabs={countriesSubTabs}
+ primaryMetric='clicks'
+ metrics={SEO_BREAKDOWN_METRICS}
+ sort={SEO_SORT}
+ getFilterLink={getFilterLink}
rowMapper={countryRowMapper}
valuesHeaderName={t('project.seo.clicks')}
detailsExtraColumns={detailsExtraColumns}
hidePercentageInDetails
- dataLoading={gscLoading}
- isLoading={isSEOLoading}
/>
- <Panel
+ <BreakdownPanel
+ dataType='seo'
+ panelId='devices'
name={t('project.devices')}
- data={topDevicesAsEntries}
icon={panelIconMapping.device}
- id='device'
- activeTabId='dv'
- disableRowClick
- getFilterLink={noopFilterLink}
+ subTabs={devicesSubTabs}
+ primaryMetric='clicks'
+ metrics={SEO_BREAKDOWN_METRICS}
+ sort={SEO_SORT}
+ getFilterLink={getFilterLink}
rowMapper={deviceRowMapper}
- capitalize
+ capitalize={['device']}
valuesHeaderName={t('project.seo.clicks')}
detailsExtraColumns={detailsExtraColumns}
hidePercentageInDetails
- dataLoading={gscLoading}
- isLoading={isSEOLoading}
/>
</div>
@@ -1190,8 +1138,7 @@ const SEOViewInner = ({ projectId, tnMapping }: SEOViewProps) => {
const SEOView = ({ projectId, tnMapping }: SEOViewProps) => {
const [searchParams] = useSearchParams()
- const { seoRefreshTrigger } = useRefreshTriggers()
- const resetKey = `seo:${projectId}:${searchParams.toString()}:${seoRefreshTrigger}`
+ const resetKey = `seo:${projectId}:${searchParams.toString()}`
return (
<TabErrorBoundary titleKey='dashboard.failedToLoadSeo' resetKey={resetKey}>
diff --git a/web/app/pages/Project/tabs/SEO/seo-utils.ts b/web/app/pages/Project/tabs/SEO/seo-utils.ts
index 987e47625..a86422d9c 100644
--- a/web/app/pages/Project/tabs/SEO/seo-utils.ts
+++ b/web/app/pages/Project/tabs/SEO/seo-utils.ts
@@ -1,9 +1,4 @@
-import dayjs from 'dayjs'
-import isoWeek from 'dayjs/plugin/isoWeek'
-import quarterOfYear from 'dayjs/plugin/quarterOfYear'
-
-dayjs.extend(isoWeek)
-dayjs.extend(quarterOfYear)
+import { TimeseriesRow } from '~/api/v2/types'
export const SEO_METRICS = {
clicks: 'clicks',
@@ -54,75 +49,25 @@ export interface DateSeriesEntry {
position: number
}
-const getBucketKey = (date: string, bucket: string): string => {
- const d = dayjs(date)
- switch (bucket) {
- case 'hour':
- case 'day':
- return date
- case 'week':
- return d.startOf('isoWeek').format('YYYY-MM-DD')
- case 'month':
- return d.startOf('month').format('YYYY-MM-DD')
- case 'quarter':
- return d.startOf('quarter').format('YYYY-MM-DD')
- case 'year':
- return d.startOf('year').format('YYYY-MM-DD')
- default:
- return date
- }
-}
-
-export const aggregateDateSeries = (
- series: DateSeriesEntry[],
- bucket: string,
-): DateSeriesEntry[] => {
- if (!series.length || bucket === 'day' || bucket === 'hour') return series
-
- const buckets = new Map<
- string,
- {
- clicks: number
- impressions: number
- weightedPosition: number
- }
- >()
- const orderedKeys: string[] = []
-
- for (const entry of series) {
- const key = getBucketKey(entry.date, bucket)
- const existing = buckets.get(key)
- if (existing) {
- existing.clicks += entry.clicks
- existing.impressions += entry.impressions
- existing.weightedPosition += entry.position * entry.impressions
- } else {
- orderedKeys.push(key)
- buckets.set(key, {
- clicks: entry.clicks,
- impressions: entry.impressions,
- weightedPosition: entry.position * entry.impressions,
- })
- }
- }
-
- return orderedKeys.map((key) => {
- const b = buckets.get(key)!
- return {
- date: key,
- clicks: b.clicks,
- impressions: b.impressions,
- ctr:
- b.impressions > 0
- ? Number(((b.clicks / b.impressions) * 100).toFixed(2))
- : 0,
- position:
- b.impressions > 0
- ? Number((b.weightedPosition / b.impressions).toFixed(1))
- : 0,
- }
- })
-}
+/**
+ * The v2 SEO timeseries is already bucketed server-side; this only reshapes its
+ * ISO timestamps into the plain date strings the chart builders plot on the x
+ * axis.
+ */
+export const seoTimeseriesToDateSeries = (
+ rows: TimeseriesRow[] | undefined,
+ timeBucket: string,
+): DateSeriesEntry[] =>
+ (rows ?? []).map((row) => ({
+ date:
+ timeBucket === 'hour'
+ ? row.timestamp.slice(0, 19).replace('T', ' ')
+ : row.timestamp.slice(0, 10),
+ clicks: Number(row.clicks ?? 0),
+ impressions: Number(row.impressions ?? 0),
+ ctr: Number(row.ctr ?? 0),
+ position: Number(row.position ?? 0),
+ }))
export const hasOrganicPositionData = (
series: OrganicPositionEntry[],
diff --git a/web/app/routes/api.analytics.ts b/web/app/routes/api.analytics.ts
index 42ae49933..c050a20f1 100644
--- a/web/app/routes/api.analytics.ts
+++ b/web/app/routes/api.analytics.ts
@@ -26,8 +26,6 @@ import {
getJourneysServer,
getJourneySessionsServer,
getGSCKeywordsServer,
- getGSCDashboardServer,
- getGSCDetailsServer,
getRevenueStatusServer,
getRevenueDataServer,
getOverallStatsServer,
@@ -52,8 +50,6 @@ import {
type JourneysResponse,
type JourneySessionsResponse,
type GSCKeywordsResponse,
- type GSCDashboardResponse,
- type GSCDetailsResponse,
type RevenueStatus,
type RevenueDataResponse,
type OverallObject,
@@ -99,8 +95,6 @@ interface ProxyRequest {
| 'getJourneys'
| 'getJourneySessions'
| 'getGSCKeywords'
- | 'getGSCDashboard'
- | 'getGSCDetails'
| 'getRevenueStatus'
| 'getRevenueData'
| 'getOverallStats'
@@ -627,46 +621,6 @@ export async function action({ request }: ActionFunctionArgs) {
})
}
- case 'getGSCDashboard': {
- const result = await getGSCDashboardServer(request, projectId, {
- period: params.period,
- from: formatDateForBackend(params.from),
- to: formatDateForBackend(params.to),
- timezone: params.timezone,
- password: password || undefined,
- timeBucket: params.timeBucket,
- filters: params.filters,
- })
- return data<ProxyResponse<GSCDashboardResponse>>({
- data: result.data,
- error: result.error
- ? Array.isArray(result.error)
- ? result.error.join(', ')
- : result.error
- : null,
- })
- }
-
- case 'getGSCDetails': {
- const result = await getGSCDetailsServer(request, projectId, {
- period: params.period,
- from: formatDateForBackend(params.from),
- to: formatDateForBackend(params.to),
- timezone: params.timezone,
- password: password || undefined,
- page: params.page,
- query: params.query,
- })
- return data<ProxyResponse<GSCDetailsResponse>>({
- data: result.data,
- error: result.error
- ? Array.isArray(result.error)
- ? result.error.join(', ')
- : result.error
- : null,
- })
- }
-
case 'getRevenueStatus': {
const result = await getRevenueStatusServer(request, projectId)
return data<ProxyResponse<RevenueStatus>>({
diff --git a/web/app/utils/analyticsUrl.ts b/web/app/utils/analyticsUrl.ts
index 04a231819..600bb6dc4 100644
--- a/web/app/utils/analyticsUrl.ts
+++ b/web/app/utils/analyticsUrl.ts
@@ -60,10 +60,6 @@ export const parseFilterKey = (rawKey: string): ParsedFilterKey | null => {
return { dimension: key, operator }
}
- if (key === 'keywords') {
- return { dimension: key, operator }
- }
-
return null
}