Skip to content

Open source alternative to Semrush and Ahrefs

Control keyword variants with a saved grouping preference (EVE-270) (#666)

Carter Smith2534bfdd4ad4
diff --git a/plugins/openseo/.claude-plugin/plugin.json b/plugins/openseo/.claude-plugin/plugin.json
index 8ffcc26a..8a92c657 100644
--- a/plugins/openseo/.claude-plugin/plugin.json
+++ b/plugins/openseo/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "openseo",
"displayName": "OpenSEO",
- "version": "1.0.2",
+ "version": "1.0.3",
"description": "Without good data, your agent gives generic advice. Keyword research, competitor research, backlinks, and site audits. All for $10/month.",
"author": {
"name": "OpenSEO",
diff --git a/plugins/openseo/.codex-plugin/plugin.json b/plugins/openseo/.codex-plugin/plugin.json
index ff9e24de..34e9ae32 100644
--- a/plugins/openseo/.codex-plugin/plugin.json
+++ b/plugins/openseo/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openseo",
- "version": "1.0.2",
+ "version": "1.0.3",
"description": "Without good data, your agent gives generic advice. Keyword research, competitor research, backlinks, and site audits. All for $10/month.",
"author": {
"name": "OpenSEO",
diff --git a/plugins/openseo/.cursor-plugin/plugin.json b/plugins/openseo/.cursor-plugin/plugin.json
index 2d1201d2..d0cebede 100644
--- a/plugins/openseo/.cursor-plugin/plugin.json
+++ b/plugins/openseo/.cursor-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openseo",
- "version": "1.0.2",
+ "version": "1.0.3",
"description": "SEO made simple. Research keywords and competitors, audit sites, track rankings, and use Search Console data from your agent.",
"author": {
"name": "Every App, Inc",
diff --git a/src/client/features/keywords/groupSharedVolumeRows.test.ts b/src/client/features/keywords/groupSharedVolumeRows.test.ts
index d42b0906..961f8c03 100644
--- a/src/client/features/keywords/groupSharedVolumeRows.test.ts
+++ b/src/client/features/keywords/groupSharedVolumeRows.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
import type { KeywordResearchRow } from "@/types/keywords";
-import { groupSharedVolumeRows, ungroupRows } from "./groupSharedVolumeRows";
+import { groupSharedVolumeRows } from "./groupSharedVolumeRows";
const SERIES = [
{ year: 2026, month: 7, searchVolume: 110000 },
@@ -21,25 +21,30 @@ function row(overrides: Partial<KeywordResearchRow>): KeywordResearchRow {
}
describe("groupSharedVolumeRows", () => {
- it("folds rows with the same volume, CPC, and monthly series under the first", () => {
+ it("keeps variants visible after their leader with their own metrics", () => {
const rows = [
row({ keyword: "caregiving" }),
row({ keyword: "respite care", searchVolume: 165000 }),
row({ keyword: "caregiver", keywordDifficulty: 45 }),
];
- const grouped = groupSharedVolumeRows(rows);
+ const grouped = groupSharedVolumeRows(rows, undefined, true);
expect(grouped.map((r) => r.keyword)).toEqual([
- "caregiving",
- "respite care",
- ]);
- expect(grouped[0].variants).toEqual([rows[2]]);
- expect(ungroupRows(grouped).map((r) => r.keyword)).toEqual([
"caregiving",
"caregiver",
"respite care",
]);
+ expect(grouped[1]).toEqual({
+ ...rows[2],
+ parentKeyword: "caregiving",
+ });
+ expect(grouped[0].parentKeyword).toBeNull();
+ expect(grouped[2].parentKeyword).toBeNull();
+ const ungrouped = groupSharedVolumeRows(rows, "caregiver", false);
+ expect(ungrouped).toEqual(
+ rows.map((keyword) => ({ ...keyword, parentKeyword: null })),
+ );
});
it("leads a group with the searched keyword as typed", () => {
@@ -48,10 +53,13 @@ describe("groupSharedVolumeRows", () => {
row({ keyword: "caregiving" }),
];
- const [group] = groupSharedVolumeRows(rows, " Caregiving");
+ const [group, child] = groupSharedVolumeRows(rows, " Caregiving", true);
expect(group.keyword).toBe("caregiving");
- expect(group.variants.map((r) => r.keyword)).toEqual(["caregiver"]);
+ expect(child).toEqual({
+ ...rows[0],
+ parentKeyword: "caregiving",
+ });
});
it("keeps rows apart when the shared number is a flat or low-volume bucket", () => {
@@ -63,6 +71,6 @@ describe("groupSharedVolumeRows", () => {
row({ keyword: "d", searchVolume: 90 }),
];
- expect(groupSharedVolumeRows(rows)).toHaveLength(4);
+ expect(groupSharedVolumeRows(rows, undefined, true)).toHaveLength(4);
});
});
diff --git a/src/client/features/keywords/groupSharedVolumeRows.ts b/src/client/features/keywords/groupSharedVolumeRows.ts
index 7d4ad123..790e3172 100644
--- a/src/client/features/keywords/groupSharedVolumeRows.ts
+++ b/src/client/features/keywords/groupSharedVolumeRows.ts
@@ -1,8 +1,8 @@
import type { KeywordResearchRow } from "@/types/keywords";
-/** A results row plus the other keywords that report the same search volume. */
+/** A visible keyword row, optionally indented beneath a shared-volume parent. */
export type KeywordResearchDisplayRow = KeywordResearchRow & {
- variants: KeywordResearchRow[];
+ parentKeyword: string | null;
};
// Only group above this volume: bucketed low volumes (10, 20, ...) collide by
@@ -27,42 +27,41 @@ function sharedVolumeKey(row: KeywordResearchRow): string | null {
/**
* Google Ads reports one volume for a whole close-variant group ("caregiving"
* / "caregiver" / "caregivers"), so those rows all claim the same searches.
- * Fold rows with an identical volume, CPC, and monthly series under the
+ * Place rows with an identical volume, CPC, and monthly series after the
* searched keyword when it is in the group, otherwise under the first one in
* the given order. Display only: every keyword keeps its own metrics
- * and stays in the data, so filters and exports still reach each variant.
+ * when grouping is enabled. With grouping off, preserve the input order.
*/
export function groupSharedVolumeRows(
rows: KeywordResearchRow[],
- searchedKeyword?: string,
+ searchedKeyword: string | undefined,
+ groupKeywords: boolean,
): KeywordResearchDisplayRow[] {
+ if (!groupKeywords) {
+ return rows.map((row) => ({ ...row, parentKeyword: null }));
+ }
// Row keywords are lowercase; the searched keyword arrives as typed.
const seed = searchedKeyword?.trim().toLowerCase();
- const groups = new Map<string, KeywordResearchDisplayRow>();
- const result: KeywordResearchDisplayRow[] = [];
+ const groups = new Map<string, KeywordResearchRow[]>();
+ const result: KeywordResearchRow[][] = [];
for (const row of rows) {
const key = sharedVolumeKey(row);
const group = key ? groups.get(key) : undefined;
- if (group && row.keyword === seed) {
- const { variants, ...leader } = group;
- Object.assign(group, row, { variants: [leader, ...variants] });
- continue;
- }
if (group) {
- group.variants.push(row);
+ if (row.keyword === seed) group.unshift(row);
+ else group.push(row);
continue;
}
- const displayRow = { ...row, variants: [] };
- if (key) groups.set(key, displayRow);
- result.push(displayRow);
+ const newGroup = [row];
+ if (key) groups.set(key, newGroup);
+ result.push(newGroup);
}
- return result;
-}
-
-export function ungroupRows(
- rows: KeywordResearchDisplayRow[],
-): KeywordResearchRow[] {
- return rows.flatMap(({ variants, ...row }) => [row, ...variants]);
+ return result.flatMap((group) =>
+ group.map((row, index) => ({
+ ...row,
+ parentKeyword: index === 0 ? null : group[0].keyword,
+ })),
+ );
}
diff --git a/src/client/features/keywords/hooks/useKeywordFiltering.ts b/src/client/features/keywords/hooks/useKeywordFiltering.ts
index 5d2488bf..a9c43e87 100644
--- a/src/client/features/keywords/hooks/useKeywordFiltering.ts
+++ b/src/client/features/keywords/hooks/useKeywordFiltering.ts
@@ -74,31 +74,33 @@ export function applyKeywordFiltersAndSort(params: {
export function useKeywordFiltering(params: {
rows: KeywordResearchRow[];
searchedKeyword: string;
+ groupKeywords: boolean;
filters: KeywordFilterValues;
sortField: SortField;
sortDir: SortDir;
}) {
// Group after filtering so a variant that passes the filters on its own
// (say, a lower difficulty) is never hidden behind one that does not.
- const filteredRows = useMemo(
- () =>
- groupSharedVolumeRows(
- applyKeywordFiltersAndSort({
- rows: params.rows,
- filters: params.filters,
- sortField: params.sortField,
- sortDir: params.sortDir,
- }),
- params.searchedKeyword,
- ),
- [
- params.filters,
- params.rows,
+ const filteredRows = useMemo(() => {
+ const rows = applyKeywordFiltersAndSort({
+ rows: params.rows,
+ filters: params.filters,
+ sortField: params.sortField,
+ sortDir: params.sortDir,
+ });
+ return groupSharedVolumeRows(
+ rows,
params.searchedKeyword,
- params.sortDir,
- params.sortField,
- ],
- );
+ params.groupKeywords,
+ );
+ }, [
+ params.filters,
+ params.groupKeywords,
+ params.rows,
+ params.searchedKeyword,
+ params.sortDir,
+ params.sortField,
+ ]);
const activeFilterCount = useMemo(
() =>
diff --git a/src/client/features/keywords/hooks/useKeywordResearchData.test.ts b/src/client/features/keywords/hooks/useKeywordResearchData.test.ts
index 7e414cb8..3b761696 100644
--- a/src/client/features/keywords/hooks/useKeywordResearchData.test.ts
+++ b/src/client/features/keywords/hooks/useKeywordResearchData.test.ts
@@ -4,7 +4,10 @@ import { describe, expect, it, vi } from "vitest";
// Workers-only bindings that don't resolve outside workerd.
vi.mock("cloudflare:workers", () => ({ env: {} }));
-import { buildKeywordResearchRequest } from "./useKeywordResearchData";
+import {
+ buildKeywordResearchRequest,
+ buildKeywordResearchQueryKey,
+} from "./useKeywordResearchData";
const baseInput = {
projectId: "project_1",
@@ -13,14 +16,23 @@ const baseInput = {
resultLimit: 150 as const,
mode: "auto" as const,
clickstream: false,
+ groupKeywords: false,
};
describe("buildKeywordResearchRequest", () => {
it("carries an explicitly selected location without a language", () => {
const request = buildKeywordResearchRequest(baseInput);
- expect(request).toMatchObject({ locationCode: 2704 });
+ expect(request).toMatchObject({ locationCode: 2704, groupKeywords: false });
expect(request).not.toHaveProperty("languageCode");
+ const grouped = buildKeywordResearchRequest({
+ ...baseInput,
+ groupKeywords: true,
+ });
+ expect(grouped).toMatchObject({ groupKeywords: true });
+ expect(buildKeywordResearchQueryKey(grouped)).not.toEqual(
+ buildKeywordResearchQueryKey(request),
+ );
});
it("leaves the location undefined for the server to resolve", () => {
diff --git a/src/client/features/keywords/hooks/useKeywordResearchData.ts b/src/client/features/keywords/hooks/useKeywordResearchData.ts
index ede39ca6..7bd35606 100644
--- a/src/client/features/keywords/hooks/useKeywordResearchData.ts
+++ b/src/client/features/keywords/hooks/useKeywordResearchData.ts
@@ -23,6 +23,7 @@ type KeywordResearchRequestInput = {
resultLimit: ResultLimit;
mode: KeywordMode;
clickstream: boolean;
+ groupKeywords: boolean;
};
type KeywordResearchQueryInput = KeywordResearchRequestInput & {
@@ -37,6 +38,7 @@ type KeywordResearchRequest = {
resultLimit: ResultLimit;
mode: KeywordMode;
clickstream: boolean;
+ groupKeywords: boolean;
};
export const KEYWORD_RESEARCH_STALE_TIME_MS = 24 * 60 * 60 * 1000;
@@ -56,6 +58,7 @@ export function buildKeywordResearchRequest(
resultLimit: input.resultLimit,
mode: input.mode,
clickstream: input.clickstream,
+ groupKeywords: input.groupKeywords,
};
}
@@ -71,6 +74,7 @@ export function buildKeywordResearchQueryKey(
request.resultLimit,
request.mode,
request.clickstream,
+ request.groupKeywords,
]
: ["keywordResearch", "idle"];
}
@@ -84,6 +88,7 @@ export function keywordResearchQueryFn(request: KeywordResearchRequest) {
resultLimit: request.resultLimit,
mode: request.mode,
clickstream: request.clickstream,
+ groupKeywords: request.groupKeywords,
},
});
}
@@ -94,6 +99,7 @@ export function useKeywordResearchData(
) {
const {
clickstream,
+ groupKeywords,
displayedLocationCode,
keywordInput,
locationCode,
@@ -110,8 +116,17 @@ export function useKeywordResearchData(
projectId,
resultLimit,
clickstream,
+ groupKeywords,
}),
- [clickstream, keywordInput, locationCode, mode, projectId, resultLimit],
+ [
+ clickstream,
+ groupKeywords,
+ keywordInput,
+ locationCode,
+ mode,
+ projectId,
+ resultLimit,
+ ],
);
const queryKey = useMemo(
() => buildKeywordResearchQueryKey(request),
diff --git a/src/client/features/keywords/hooks/usePreferredKeywordGrouping.ts b/src/client/features/keywords/hooks/usePreferredKeywordGrouping.ts
new file mode 100644
index 00000000..987c2ca0
--- /dev/null
+++ b/src/client/features/keywords/hooks/usePreferredKeywordGrouping.ts
@@ -0,0 +1,46 @@
+import { useEffect, useState } from "react";
+import { z } from "zod";
+
+const storageKey = (projectId: string) =>
+ `keyword-preferred-grouping:${projectId}`;
+
+export function loadPreferredGrouping(projectId: string): boolean {
+ try {
+ const raw = localStorage.getItem(storageKey(projectId));
+ if (!raw) return false;
+ return z.boolean().parse(JSON.parse(raw));
+ } catch {
+ return false;
+ }
+}
+
+/** Like country selection, grouping is a per-project browser preference. */
+export function usePreferredKeywordGrouping(projectId: string) {
+ const [preference, setPreference] = useState(() => ({
+ projectId,
+ groupKeywords: loadPreferredGrouping(projectId),
+ }));
+ const groupKeywords =
+ preference.projectId === projectId
+ ? preference.groupKeywords
+ : loadPreferredGrouping(projectId);
+
+ useEffect(() => {
+ if (preference.projectId === projectId) return;
+ setPreference({ projectId, groupKeywords });
+ }, [groupKeywords, preference.projectId, projectId]);
+
+ function setGroupKeywords(nextGroupKeywords: boolean) {
+ setPreference({ projectId, groupKeywords: nextGroupKeywords });
+ try {
+ localStorage.setItem(
+ storageKey(projectId),
+ JSON.stringify(nextGroupKeywords),
+ );
+ } catch {
+ // Keep the current choice usable when browser storage is unavailable.
+ }
+ }
+
+ return { groupKeywords, setGroupKeywords };
+}
diff --git a/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx b/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx
index 5789b843..3dc98e7e 100644
--- a/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx
+++ b/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx
@@ -117,22 +117,27 @@ function DesktopTableCard({ controller }: Props) {
sheetsExportRows,
showFilters,
} = controller;
- const { page, pageSize, pageRows, setPage, setPageSize } =
- useKeywordResearchPagination(filteredRows);
- const keywordCount = filteredRows.reduce(
- (count, row) => count + 1 + row.variants.length,
- 0,
- );
+ const {
+ page,
+ pageSize,
+ pageRows,
+ setPage,
+ setPageSize,
+ start,
+ end,
+ totalPages,
+ } = useKeywordResearchPagination(filteredRows);
+ const keywordCount = filteredRows.length;
const keywordCountLabel =
selectedRows.size > 0
- ? `${selectedRows.size} of ${filteredRows.length} selected`
+ ? `${selectedRows.size} selected`
: activeFilterCount > 0
? `Showing ${keywordCount} of ${rows.length} keywords`
: `Showing ${keywordCount} keywords`;
const canExport = filteredRows.length > 0;
- const selectedExportRows = filteredRows
+ const selectedExportRows = rows
.filter((row) => selectedRows.has(row.keyword))
.map(keywordResearchExportRow);
const handleExportToSheets = () => {
@@ -160,7 +165,7 @@ function DesktopTableCard({ controller }: Props) {
return (
<div className="flex-1 flex flex-col min-w-0 border border-base-300 rounded-xl bg-base-100 overflow-hidden">
- <div className="shrink-0 flex items-center gap-2 px-4 py-2 border-b border-base-300">
+ <div className="shrink-0 flex flex-wrap items-center gap-2 px-4 py-2 border-b border-base-300">
<button
className={`btn btn-ghost btn-sm gap-1.5 ${showFilters ? "btn-active" : ""}`}
onClick={() => controller.setShowFilters((current) => !current)}
@@ -252,6 +257,9 @@ function DesktopTableCard({ controller }: Props) {
/>
{filteredRows.length > 0 ? (
<KeywordResearchPagination
+ start={start}
+ end={end}
+ totalPages={totalPages}
page={page}
pageSize={pageSize}
totalCount={filteredRows.length}
diff --git a/src/client/features/keywords/page/KeywordResearchDesktopTable.tsx b/src/client/features/keywords/page/KeywordResearchDesktopTable.tsx
index d033869e..2cc2ea6c 100644
--- a/src/client/features/keywords/page/KeywordResearchDesktopTable.tsx
+++ b/src/client/features/keywords/page/KeywordResearchDesktopTable.tsx
@@ -35,25 +35,6 @@ type Props = {
handleRowClick: (row: KeywordResearchRow) => void;
};
-/** The close variants that report the same search volume as the row above. */
-function SharedVolumeVariants({
- variants,
-}: {
- variants: KeywordResearchRow[];
-}) {
- if (variants.length === 0) return null;
- const keywords = variants.map((variant) => variant.keyword).join(", ");
-
- return (
- <span
- className="block max-w-64 truncate text-xs font-normal text-base-content/50"
- title={keywords}
- >
- {keywords}
- </span>
- );
-}
-
const keywordColumnHelper = createColumnHelper<KeywordResearchDisplayRow>();
export function KeywordResearchDesktopTable({
@@ -91,14 +72,19 @@ export function KeywordResearchDesktopTable({
/>
),
cell: ({ row }) => (
- <div className="min-w-48 md:min-w-0">
+ <div
+ className={`min-w-48 md:min-w-0 ${row.original.parentKeyword ? "pl-4" : ""}`}
+ >
<span
- className="block whitespace-normal break-words font-medium capitalize md:truncate"
- title={row.original.keyword}
+ className={`block whitespace-normal break-words capitalize md:truncate ${row.original.parentKeyword ? "font-normal" : "font-medium"}`}
+ title={
+ row.original.parentKeyword
+ ? `${row.original.keyword}: matching reported volume with ${row.original.parentKeyword}. Shared volumes may overlap.`
+ : row.original.keyword
+ }
>
{row.original.keyword}
</span>
- <SharedVolumeVariants variants={row.original.variants} />
</div>
),
meta: {
@@ -117,7 +103,8 @@ export function KeywordResearchDesktopTable({
className="justify-end"
/>
),
- cell: ({ getValue }) => formatNumber(getValue()),
+ cell: ({ row, getValue }) =>
+ row.original.parentKeyword ? null : formatNumber(getValue()),
meta: {
headerClassName: "text-right",
cellClassName:
@@ -136,7 +123,8 @@ export function KeywordResearchDesktopTable({
className="justify-end"
/>
),
- cell: ({ getValue }) => {
+ cell: ({ row, getValue }) => {
+ if (row.original.parentKeyword) return null;
const value = getValue();
return value == null ? "-" : value.toFixed(2);
},
@@ -158,7 +146,8 @@ export function KeywordResearchDesktopTable({
className="justify-end"
/>
),
- cell: ({ getValue }) => {
+ cell: ({ row, getValue }) => {
+ if (row.original.parentKeyword) return null;
const value = getValue();
return value == null ? "-" : value.toFixed(2);
},
diff --git a/src/client/features/keywords/page/KeywordResearchMobileResults.tsx b/src/client/features/keywords/page/KeywordResearchMobileResults.tsx
index 62d9f215..ac6cfda5 100644
--- a/src/client/features/keywords/page/KeywordResearchMobileResults.tsx
+++ b/src/client/features/keywords/page/KeywordResearchMobileResults.tsx
@@ -92,12 +92,17 @@ function MobileKeywordResults({ controller }: Props) {
sheetsExportRows,
showFilters,
} = controller;
- const { page, pageSize, pageRows, setPage, setPageSize } =
- useKeywordResearchPagination(filteredRows);
- const keywordCount = filteredRows.reduce(
- (count, row) => count + 1 + row.variants.length,
- 0,
- );
+ const {
+ page,
+ pageSize,
+ pageRows,
+ setPage,
+ setPageSize,
+ start,
+ end,
+ totalPages,
+ } = useKeywordResearchPagination(filteredRows);
+ const keywordCount = filteredRows.length;
const keywordCountLabel =
selectedRows.size > 0
@@ -107,7 +112,7 @@ function MobileKeywordResults({ controller }: Props) {
: `Showing ${keywordCount} keywords`;
const canExport = filteredRows.length > 0;
- const selectedExportRows = filteredRows
+ const selectedExportRows = rows
.filter((row) => selectedRows.has(row.keyword))
.map(keywordResearchExportRow);
const handleExportToSheets = () => {
@@ -146,7 +151,7 @@ function MobileKeywordResults({ controller }: Props) {
</div>
) : null}
- <div className="shrink-0 flex items-center gap-2 px-4 py-2 border-b border-base-300 bg-base-100">
+ <div className="shrink-0 flex flex-wrap items-center gap-2 px-4 py-2 border-b border-base-300 bg-base-100">
<button
className={`btn btn-ghost btn-xs gap-1 ${showFilters ? "btn-active" : ""}`}
onClick={() => controller.setShowFilters((current) => !current)}
@@ -238,6 +243,9 @@ function MobileKeywordResults({ controller }: Props) {
/>
{filteredRows.length > 0 ? (
<KeywordResearchPagination
+ start={start}
+ end={end}
+ totalPages={totalPages}
page={page}
pageSize={pageSize}
totalCount={filteredRows.length}
diff --git a/src/client/features/keywords/page/KeywordResearchPagination.test.ts b/src/client/features/keywords/page/KeywordResearchPagination.test.ts
new file mode 100644
index 00000000..f61475bf
--- /dev/null
+++ b/src/client/features/keywords/page/KeywordResearchPagination.test.ts
@@ -0,0 +1,51 @@
+import { expect, it } from "vitest";
+import type { KeywordResearchDisplayRow } from "../groupSharedVolumeRows";
+import { keywordResearchPageEnds } from "./KeywordResearchPagination";
+
+function row(
+ keyword: string,
+ parentKeyword: string | null = null,
+): KeywordResearchDisplayRow {
+ return {
+ keyword,
+ parentKeyword,
+ searchVolume: null,
+ cpc: null,
+ competition: null,
+ keywordDifficulty: null,
+ intent: "unknown",
+ trend: [],
+ };
+}
+
+it("keeps the boundary parent and all its children on the same page", () => {
+ const rows = [
+ ...Array.from({ length: 49 }, (_, index) => row(String(index))),
+ row("parent"),
+ row("child1", "parent"),
+ row("child2", "parent"),
+ ...Array.from({ length: 50 }, (_, index) => row(`next${index}`)),
+ ];
+ const ends = keywordResearchPageEnds(rows, 50);
+ expect(ends).toEqual([52, 102]);
+ const pages = ends.map((end, index) => rows.slice(ends[index - 1] ?? 0, end));
+ expect(pages.flat()).toEqual(rows);
+ expect(pages.every((page) => page[0].parentKeyword === null)).toBe(true);
+});
+
+it("allows an oversized family and retains ordinary boundaries with grouping off", () => {
+ const rows = [
+ row("parent"),
+ row("one", "parent"),
+ row("two", "parent"),
+ row("next"),
+ ];
+ expect(keywordResearchPageEnds(rows, 2)).toEqual([3, 4]);
+ expect(
+ keywordResearchPageEnds(
+ rows.map((item) => ({ ...item, parentKeyword: null })),
+ 2,
+ ),
+ ).toEqual([2, 4]);
+ expect(keywordResearchPageEnds([], 50)).toEqual([]);
+});
diff --git a/src/client/features/keywords/page/KeywordResearchPagination.tsx b/src/client/features/keywords/page/KeywordResearchPagination.tsx
index 06b74e4c..827d23ed 100644
--- a/src/client/features/keywords/page/KeywordResearchPagination.tsx
+++ b/src/client/features/keywords/page/KeywordResearchPagination.tsx
@@ -1,6 +1,6 @@
import { ChevronLeft, ChevronRight } from "lucide-react";
import { useEffect, useMemo, useState } from "react";
-import type { KeywordResearchRow } from "@/types/keywords";
+import type { KeywordResearchDisplayRow } from "../groupSharedVolumeRows";
const KEYWORD_RESEARCH_PAGE_SIZES = [50, 100, 300, 500] as const;
const DEFAULT_KEYWORD_RESEARCH_PAGE_SIZE = 50;
@@ -13,6 +13,9 @@ type Props = {
page: number;
pageSize: KeywordResearchPageSize;
totalCount: number;
+ totalPages: number;
+ start: number;
+ end: number;
onPageChange: (page: number) => void;
onPageSizeChange: (pageSize: KeywordResearchPageSize) => void;
};
@@ -21,13 +24,12 @@ export function KeywordResearchPagination({
page,
pageSize,
totalCount,
+ totalPages,
+ start,
+ end,
onPageChange,
onPageSizeChange,
}: Props) {
- const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
- const start = totalCount === 0 ? 0 : (page - 1) * pageSize + 1;
- const end = Math.min(totalCount, page * pageSize);
-
return (
<div className="flex flex-col gap-3 border-t border-base-300 px-4 py-3 sm:flex-row sm:items-center sm:justify-between">
<div className="text-sm tabular-nums text-base-content/70">
@@ -89,14 +91,36 @@ function parseKeywordResearchPageSize(value: string): KeywordResearchPageSize {
);
}
-export function useKeywordResearchPagination<Row extends KeywordResearchRow>(
- rows: Row[],
+export function keywordResearchPageEnds(
+ rows: KeywordResearchDisplayRow[],
+ pageSize: number,
+) {
+ const ends: number[] = [];
+ for (let start = 0; start < rows.length; ) {
+ let end = Math.min(start + pageSize, rows.length);
+ // Finish the last family before starting the next page.
+ while (end < rows.length && rows[end].parentKeyword !== null) end++;
+ ends.push(end);
+ start = end;
+ }
+ return ends;
+}
+
+export function useKeywordResearchPagination(
+ rows: KeywordResearchDisplayRow[],
) {
const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState<KeywordResearchPageSize>(() =>
getStoredKeywordResearchPageSize(),
);
- const totalPages = Math.max(1, Math.ceil(rows.length / pageSize));
+ const pageEnds = useMemo(
+ () => keywordResearchPageEnds(rows, pageSize),
+ [rows, pageSize],
+ );
+ const totalPages = Math.max(1, pageEnds.length);
+ const currentPage = Math.min(page, totalPages);
+ const start = pageEnds[currentPage - 2] ?? 0;
+ const end = pageEnds[currentPage - 1] ?? 0;
useEffect(() => {
setPage(1);
@@ -106,13 +130,12 @@ export function useKeywordResearchPagination<Row extends KeywordResearchRow>(
setPage((current) => Math.min(current, totalPages));
}, [totalPages]);
- const pageRows = useMemo(() => {
- const start = (page - 1) * pageSize;
- return rows.slice(start, start + pageSize);
- }, [page, pageSize, rows]);
+ const pageRows = useMemo(() => rows.slice(start, end), [start, end, rows]);
return {
- page,
+ page: currentPage,
+ start: rows.length === 0 ? 0 : start + 1,
+ end,
pageSize,
pageRows,
setPage,
diff --git a/src/client/features/keywords/page/KeywordResearchSearchBar.tsx b/src/client/features/keywords/page/KeywordResearchSearchBar.tsx
index baf44ab3..6f9ab94c 100644
--- a/src/client/features/keywords/page/KeywordResearchSearchBar.tsx
+++ b/src/client/features/keywords/page/KeywordResearchSearchBar.tsx
@@ -129,49 +129,65 @@ export function KeywordResearchSearchBar({ controller }: Props) {
) : null;
}}
</controlsForm.Field>
- <controlsForm.Field name="locationCode">
- {(locationField) =>
- isLabsLocationCode(locationField.state.value) ? (
- <controlsForm.Field name="clickstream">
- {(field) => (
- <div className="flex items-center gap-2">
- <label className="label cursor-pointer justify-start gap-2 p-0">
- <input
- type="checkbox"
- className="toggle toggle-sm toggle-primary"
- checked={field.state.value}
- onChange={(event) =>
- field.handleChange(event.target.checked)
- }
- />
- <span className="text-sm font-medium text-base-content/80">
- Clickstream-refined volumes
- </span>
- </label>
- <div
- className="tooltip tooltip-right"
- data-tip="Google reports one combined search volume for similar keywords (e.g. 'seo tool' and 'seo tools'). Turn this on to estimate each keyword's own volume. Costs 2x the credits."
- >
- <Info className="size-3.5 text-base-content/50" />
+ <div className="flex flex-wrap items-center gap-x-6 gap-y-2">
+ <label className="label cursor-pointer justify-start gap-2 p-0">
+ <input
+ type="checkbox"
+ role="switch"
+ className="toggle toggle-sm toggle-primary"
+ checked={controller.groupKeywords}
+ onChange={(event) =>
+ controller.setGroupKeywords(event.target.checked)
+ }
+ />
+ <span className="text-sm font-medium text-base-content/80">
+ Group keywords
+ </span>
+ </label>
+ <controlsForm.Field name="locationCode">
+ {(locationField) =>
+ isLabsLocationCode(locationField.state.value) ? (
+ <controlsForm.Field name="clickstream">
+ {(field) => (
+ <div className="flex items-center gap-2">
+ <label className="label cursor-pointer justify-start gap-2 p-0">
+ <input
+ type="checkbox"
+ className="toggle toggle-sm toggle-primary"
+ checked={field.state.value}
+ onChange={(event) =>
+ field.handleChange(event.target.checked)
+ }
+ />
+ <span className="text-sm font-medium text-base-content/80">
+ Clickstream-refined volumes
+ </span>
+ </label>
+ <div
+ className="tooltip tooltip-right"
+ data-tip="Google reports one combined search volume for similar keywords (e.g. 'seo tool' and 'seo tools'). Turn this on to estimate each keyword's own volume. Costs 2x the credits."
+ >
+ <Info className="size-3.5 text-base-content/50" />
+ </div>
</div>
- </div>
- )}
- </controlsForm.Field>
- ) : (
- <div
- className="flex items-start gap-2 rounded-lg border border-info/30 bg-info/10 px-3 py-2 text-sm text-base-content/80"
- role="status"
- >
- <Info className="mt-0.5 size-4 shrink-0 text-info" />
- <span>
- Keyword data for this country comes from Google Ads — search
- volume, CPC, and trends are available, but difficulty and
- intent are not.
- </span>
- </div>
- )
- }
- </controlsForm.Field>
+ )}
+ </controlsForm.Field>
+ ) : (
+ <div
+ className="flex items-start gap-2 rounded-lg border border-info/30 bg-info/10 px-3 py-2 text-sm text-base-content/80"
+ role="status"
+ >
+ <Info className="mt-0.5 size-4 shrink-0 text-info" />
+ <span>
+ Keyword data for this country comes from Google Ads — search
+ volume, CPC, and trends are available, but difficulty and
+ intent are not.
+ </span>
+ </div>
+ )
+ }
+ </controlsForm.Field>
+ </div>
</div>
</div>
);
diff --git a/src/client/features/keywords/state/keywordControllerActions.ts b/src/client/features/keywords/state/keywordControllerActions.ts
index 90319910..04aad54b 100644
--- a/src/client/features/keywords/state/keywordControllerActions.ts
+++ b/src/client/features/keywords/state/keywordControllerActions.ts
@@ -11,10 +11,7 @@ import type {
ResultLimit,
} from "@/client/features/keywords/keywordResearchTypes";
import type { KeywordResearchControllerInput } from "./useKeywordResearchController";
-import {
- ungroupRows,
- type KeywordResearchDisplayRow,
-} from "@/client/features/keywords/groupSharedVolumeRows";
+import type { KeywordResearchDisplayRow } from "@/client/features/keywords/groupSharedVolumeRows";
export const KEYWORD_RESEARCH_HEADERS = [
"Keyword",
@@ -69,6 +66,7 @@ export function buildKeywordSearchKey(params: {
resultLimit: ResultLimit;
mode: KeywordMode;
clickstream: boolean;
+ groupKeywords: boolean;
}) {
return [
parseKeywordInput(params.keyword).join(""),
@@ -76,6 +74,7 @@ export function buildKeywordSearchKey(params: {
params.resultLimit,
params.mode,
params.clickstream ? "cs" : "",
+ params.groupKeywords ? "grouped" : "",
].join("|");
}
@@ -149,7 +148,7 @@ export function useSaveAndExportActions(params: SaveExportActionParams) {
};
const sheetsExportRows: CsvValue[][] = useMemo(
- () => ungroupRows(filteredRows).map(keywordResearchExportRow),
+ () => filteredRows.map(keywordResearchExportRow),
[filteredRows],
);
diff --git a/src/client/features/keywords/state/useKeywordResearchController.ts b/src/client/features/keywords/state/useKeywordResearchController.ts
index a272503e..a533c0e4 100644
--- a/src/client/features/keywords/state/useKeywordResearchController.ts
+++ b/src/client/features/keywords/state/useKeywordResearchController.ts
@@ -4,6 +4,7 @@ import {
type KeywordControlsValues,
} from "@/client/features/keywords/hooks/useKeywordControlsForm";
import { useKeywordFiltering } from "@/client/features/keywords/hooks/useKeywordFiltering";
+import { usePreferredKeywordGrouping } from "@/client/features/keywords/hooks/usePreferredKeywordGrouping";
import { useLocalKeywordFilters } from "@/client/features/keywords/hooks/useLocalKeywordFilters";
import { useKeywordResearchData } from "@/client/features/keywords/hooks/useKeywordResearchData";
import { useKeywordSelection } from "@/client/features/keywords/hooks/useKeywordSelection";
@@ -52,6 +53,9 @@ export function useKeywordResearchController(
) {
const { displayedLocationCode, locationCode, setPreferredLocationCode } =
input;
+ const { groupKeywords, setGroupKeywords } = usePreferredKeywordGrouping(
+ input.projectId,
+ );
const {
filtersForm,
values: filterValues,
@@ -111,6 +115,7 @@ export function useKeywordResearchController(
resultLimit: input.resultLimit,
mode: input.keywordMode,
clickstream: input.clickstream,
+ groupKeywords,
},
addSearch,
);
@@ -124,6 +129,7 @@ export function useKeywordResearchController(
resultLimit: input.resultLimit,
mode: input.keywordMode,
clickstream: input.clickstream,
+ groupKeywords,
})
: null;
@@ -149,7 +155,7 @@ export function useKeywordResearchController(
},
);
- // The URL is the source of truth for paid keyword research queries. This
+ // The URL and saved grouping preference define keyword research queries. This
// effect only resets UI state around a new query key; TanStack Query owns the
// actual fetch, cache, dedupe, and error lifecycle.
useEffect(() => {
@@ -177,6 +183,7 @@ export function useKeywordResearchController(
]);
const { filteredRows, activeFilterCount } = useKeywordFiltering({
+ groupKeywords,
rows,
searchedKeyword,
filters: filterValues,
@@ -236,6 +243,8 @@ export function useKeywordResearchController(
};
return {
+ groupKeywords,
+ setGroupKeywords,
activeFilterCount,
activeSerpKeyword,
confirmSave,
diff --git a/src/client/features/search-tabs/SearchTabStrip.tsx b/src/client/features/search-tabs/SearchTabStrip.tsx
index fddd5736..d96f3b34 100644
--- a/src/client/features/search-tabs/SearchTabStrip.tsx
+++ b/src/client/features/search-tabs/SearchTabStrip.tsx
@@ -11,6 +11,7 @@ import {
} from "@/client/features/keywords/hooks/useKeywordResearchData";
import { getBacklinksOverview } from "@/serverFunctions/backlinks";
import { getDomainOverview } from "@/serverFunctions/domain";
+import { loadPreferredGrouping } from "@/client/features/keywords/hooks/usePreferredKeywordGrouping";
export type { SearchTab } from "./types";
type Props = {
@@ -217,6 +218,7 @@ function getSearchTabQueryConfig(
resultLimit: input.resultLimit,
mode: input.mode,
clickstream: input.clickstream,
+ groupKeywords: loadPreferredGrouping(projectId),
});
return {
diff --git a/src/server/features/keywords/services/research/research-data.ts b/src/server/features/keywords/services/research/research-data.ts
index c7508a71..eade4b2c 100644
--- a/src/server/features/keywords/services/research/research-data.ts
+++ b/src/server/features/keywords/services/research/research-data.ts
@@ -19,6 +19,7 @@ type FetchResearchRowsParams = {
resultLimit: number;
source: KeywordSource;
includeClickstreamData?: boolean;
+ ignoreSynonyms?: boolean;
// Attribute the DataForSEO spend to a specific feature (e.g. "agent");
// defaults to the path-derived feature when omitted.
creditFeature?: CreditFeature;
@@ -126,6 +127,7 @@ async function fetchRelatedRows(
limit: params.resultLimit,
depth: 3,
includeClickstreamData: params.includeClickstreamData,
+ ignoreSynonyms: params.ignoreSynonyms,
creditFeature: params.creditFeature,
});
@@ -156,6 +158,7 @@ export async function fetchResearchRowsBySource(
languageCode: params.languageCode,
limit: params.resultLimit,
includeClickstreamData: params.includeClickstreamData,
+ ignoreSynonyms: params.ignoreSynonyms,
creditFeature: params.creditFeature,
}),
);
@@ -168,6 +171,7 @@ export async function fetchResearchRowsBySource(
languageCode: params.languageCode,
limit: params.resultLimit,
includeClickstreamData: params.includeClickstreamData,
+ ignoreSynonyms: params.ignoreSynonyms,
creditFeature: params.creditFeature,
}),
);
diff --git a/src/server/features/keywords/services/research/research.test.ts b/src/server/features/keywords/services/research/research.test.ts
index 3cf56349..1a14e368 100644
--- a/src/server/features/keywords/services/research/research.test.ts
+++ b/src/server/features/keywords/services/research/research.test.ts
@@ -60,8 +60,12 @@ it("keeps shared-volume keywords independently filterable through research and c
"adult day care",
"care home",
].map((keyword) => ({ ...seed, keyword, searchVolume: 500 }));
- mocks.fetchRows.mockImplementation(async ({ source }) =>
- source === "suggestions" ? [seed] : [opportunity, ...siblings],
+ mocks.fetchRows.mockImplementation(async ({ source, ignoreSynonyms }) =>
+ source === "suggestions"
+ ? [seed]
+ : ignoreSynonyms
+ ? siblings
+ : [opportunity, ...siblings],
);
const input = {
projectId: "project_1",
@@ -71,6 +75,7 @@ it("keeps shared-volume keywords independently filterable through research and c
resultLimit: 150 as const,
mode: "auto" as const,
clickstream: false,
+ groupKeywords: true,
};
const customer = {
organizationId: "org_1",
@@ -113,4 +118,19 @@ it("keeps shared-volume keywords independently filterable through research and c
sortDir: "asc",
});
expect(filtered).toEqual([opportunity]);
+ for (const params of mocks.fetchRows.mock.calls.slice(0, 2)) {
+ expect(params[0]).toMatchObject({ ignoreSynonyms: false });
+ }
+ const coreOnly = await research({ ...input, groupKeywords: false }, customer);
+ // The thin core-only set also exercises the related-keywords fallback.
+ expect(mocks.fetchRows).toHaveBeenCalledTimes(5);
+ for (const params of mocks.fetchRows.mock.calls.slice(2)) {
+ expect(params[0]).toMatchObject({ ignoreSynonyms: true });
+ }
+ expect(coreOnly.rows).not.toContainEqual(opportunity);
+ expect(await research({ ...input, groupKeywords: false }, customer)).toEqual(
+ coreOnly,
+ );
+ expect(await research(input, customer)).toEqual(fresh);
+ expect(mocks.fetchRows).toHaveBeenCalledTimes(5);
});
diff --git a/src/server/features/keywords/services/research/research.ts b/src/server/features/keywords/services/research/research.ts
index 91a3ae40..4663126e 100644
--- a/src/server/features/keywords/services/research/research.ts
+++ b/src/server/features/keywords/services/research/research.ts
@@ -84,6 +84,7 @@ async function fetchRowsFromSource(
languageCode: input.languageCode,
resultLimit: opts.resultLimit ?? input.resultLimit,
includeClickstreamData: input.clickstream,
+ ignoreSynonyms: !input.groupKeywords,
creditFeature: opts.creditFeature,
},
billingCustomer,
@@ -218,6 +219,7 @@ async function buildResearchCacheKey(
mode,
depth: 3,
clickstream: input.clickstream,
+ groupKeywords: input.groupKeywords,
});
}
@@ -260,12 +262,12 @@ export async function research(
const seedKeyword = uniqueKeywords[0];
const provider = getKeywordDataProvider(input.locationCode);
- // Labs source modes and clickstream refinement don't exist for
- // Google-Ads-served countries; collapse both so equivalent requests share
+ // Labs source modes, clickstream, and synonym filtering don't exist for
+ // Google-Ads-served countries; normalize them so equivalent requests share
// one cache entry.
const effectiveInput: ResolvedResearchKeywordsInput =
provider === "google_ads"
- ? { ...input, mode: "auto", clickstream: false }
+ ? { ...input, mode: "auto", clickstream: false, groupKeywords: false }
: input;
const mode = effectiveInput.mode ?? "auto";
const cacheKey = await buildResearchCacheKey(
diff --git a/src/server/lib/dataforseo/labs.test.ts b/src/server/lib/dataforseo/labs.test.ts
new file mode 100644
index 00000000..5895acd1
--- /dev/null
+++ b/src/server/lib/dataforseo/labs.test.ts
@@ -0,0 +1,52 @@
+import { afterEach, expect, it, vi } from "vitest";
+import {
+ fetchRelatedKeywords,
+ fetchKeywordSuggestions,
+ fetchKeywordIdeas,
+} from "./labs";
+
+vi.mock("@/server/lib/runtime-env", () => ({
+ getRequiredEnvValue: vi.fn(async () => "test-api-key"),
+}));
+
+afterEach(() => vi.unstubAllGlobals());
+
+it("sends synonym filtering for every Labs research source and preserves omitted defaults", async () => {
+ const fetchMock = vi.fn<typeof fetch>().mockImplementation(async (url) =>
+ Response.json({
+ status_code: 20000,
+ tasks: [
+ {
+ status_code: 20000,
+ path: new URL(url instanceof Request ? url.url : url).pathname
+ .split("/")
+ .filter(Boolean),
+ cost: 0,
+ result: [{ items: [] }],
+ },
+ ],
+ }),
+ );
+ vi.stubGlobal("fetch", fetchMock);
+ for (const fetchKeywords of [
+ fetchRelatedKeywords,
+ fetchKeywordSuggestions,
+ fetchKeywordIdeas,
+ ]) {
+ for (const ignoreSynonyms of [true, false, undefined]) {
+ await fetchKeywords({
+ keyword: "caregiving",
+ locationCode: 2840,
+ languageCode: "en",
+ limit: 150,
+ ignoreSynonyms,
+ });
+ const body = fetchMock.mock.lastCall?.[1]?.body;
+ if (typeof body !== "string")
+ throw new Error("Expected JSON request body");
+ expect(JSON.parse(body)).toEqual([
+ expect.objectContaining({ ignore_synonyms: ignoreSynonyms ?? false }),
+ ]);
+ }
+ }
+});
diff --git a/src/server/lib/dataforseo/labs.ts b/src/server/lib/dataforseo/labs.ts
index c3c5512b..4b555b4f 100644
--- a/src/server/lib/dataforseo/labs.ts
+++ b/src/server/lib/dataforseo/labs.ts
@@ -151,6 +151,7 @@ export async function fetchRelatedKeywords(input: {
limit: number;
depth?: number;
includeClickstreamData?: boolean;
+ ignoreSynonyms?: boolean;
}): Promise<DataforseoApiResponse<RelatedKeywordItem[]>> {
const response = await dataforseoPost<
DataforseoItemsTask<RelatedKeywordItem>
@@ -161,6 +162,7 @@ export async function fetchRelatedKeywords(input: {
language_code: input.languageCode,
limit: input.limit,
depth: input.depth ?? 3,
+ ignore_synonyms: input.ignoreSynonyms ?? false,
// Clickstream-refined volumes DOUBLE the request cost, so they are
// opt-in — see specs/0004-keyword-data-source-routing.md.
include_clickstream_data: input.includeClickstreamData ?? false,
@@ -180,6 +182,7 @@ export async function fetchKeywordSuggestions(input: {
languageCode: string;
limit: number;
includeClickstreamData?: boolean;
+ ignoreSynonyms?: boolean;
}): Promise<DataforseoApiResponse<LabsKeywordDataItem[]>> {
const response = await dataforseoPost<
DataforseoItemsTask<LabsKeywordDataItem>
@@ -192,7 +195,7 @@ export async function fetchKeywordSuggestions(input: {
include_clickstream_data: input.includeClickstreamData ?? false,
include_serp_info: false,
include_seed_keyword: true,
- ignore_synonyms: false,
+ ignore_synonyms: input.ignoreSynonyms ?? false,
exact_match: false,
},
]);
@@ -209,6 +212,7 @@ export async function fetchKeywordIdeas(input: {
languageCode: string;
limit: number;
includeClickstreamData?: boolean;
+ ignoreSynonyms?: boolean;
}): Promise<DataforseoApiResponse<LabsKeywordDataItem[]>> {
const response = await dataforseoPost<
DataforseoItemsTask<LabsKeywordDataItem>
@@ -220,7 +224,7 @@ export async function fetchKeywordIdeas(input: {
limit: input.limit,
include_clickstream_data: input.includeClickstreamData ?? false,
include_serp_info: false,
- ignore_synonyms: false,
+ ignore_synonyms: input.ignoreSynonyms ?? false,
closely_variants: false,
},
]);
diff --git a/src/server/mcp/tools/research-keywords.ts b/src/server/mcp/tools/research-keywords.ts
index 757e4940..57f24e3b 100644
--- a/src/server/mcp/tools/research-keywords.ts
+++ b/src/server/mcp/tools/research-keywords.ts
@@ -44,6 +44,12 @@ const inputSchema = {
.describe(
"Refine search volumes with clickstream data, which disaggregates Google Ads' grouped close-variant volumes (plurals/misspellings). DOUBLES the credit cost of each seed. Default false (standard Google-Ads-derived volumes). No effect for countries served from Google Ads data.",
),
+ groupKeywords: z
+ .boolean()
+ .optional()
+ .describe(
+ "Include similar keyword variants that can share volume, CPC, and competition. Default false returns only core keywords (DataForSEO ignore_synonyms=true). True includes variants (ignore_synonyms=false). This filters keywords, not metric estimates. Do not sum shared volumes. No effect for countries served from Google Ads data.",
+ ),
} as const;
type Args = z.infer<z.ZodObject<typeof inputSchema>>;
@@ -138,6 +144,7 @@ export const researchKeywordsTool = {
resultLimit: args.resultLimit ?? 150,
mode: "auto",
clickstream: args.includeClickstreamData ?? false,
+ groupKeywords: args.groupKeywords ?? false,
},
context.billing,
);
diff --git a/src/types/schemas/keywords.ts b/src/types/schemas/keywords.ts
index b1ccfea6..71a4cde0 100644
--- a/src/types/schemas/keywords.ts
+++ b/src/types/schemas/keywords.ts
@@ -29,6 +29,7 @@ export const researchKeywordsSchema = z.object({
.default("auto"),
// Clickstream-refined volumes double the DataForSEO request cost; opt-in.
clickstream: z.boolean().optional().default(false),
+ groupKeywords: z.boolean().optional().default(false),
});
export const savedKeywordMetricSchema = z.object({