feat: add RelatedSearchesResult parser for extracting related search queries

.changeset/smart-dragons-change.md

@@ -0,0 +1,7 @@
+---
+"google-sr-selectors": minor
+---
+
+Add RelatedSearchesSelector for parsing related search queries
+
+Add new CSS selectors for extracting related search suggestions that appear at the bottom of Google search results.

.changeset/ten-teams-tickle.md

@@ -0,0 +1,22 @@
+---
+"google-sr": minor
+---
+
+Add RelatedSearchesResult parser for extracting related search queries
+
+Add `RelatedSearchesResult` parser to extract the "Related searches" suggestions that Google displays at the bottom of search results to help users find similar queries.
+
+```ts
+import { RelatedSearchesResult, search } from 'google-sr';
+
+const results = await search({
+  query: 'nodejs frameworks',
+  parsers: [RelatedSearchesResult],
+});
+
+// results[0].queries might contain: ["express.js", "react.js", "vue.js", ...]
+```
+
+The parser returns a `RelatedSearchesResultNode` with:
+- `type`: `"RELATED_SEARCHES"`
+- `queries`: Array of related search query strings

packages/google-sr-selectors/src/index.ts

@@ -82,3 +82,8 @@ export const NewsSearchSelector = {
 	source: ".qXLe6d.dXDvrc .fYyStc",
 	thumbnail_image: "table.gNEi4d > tbody > tr > td > div > img",
 };
+
+export const RelatedSearchesSelector = {
+	query_item: "a.ZWRArf", // Each related query link
+	text: "span.fYyStc", // Visible query string inside the <a>
+};

packages/google-sr/src/constants.ts

@@ -4,6 +4,7 @@ import type {
 	KnowledgePanelResultNode,
 	NewsResultNode,
 	OrganicResultNode,
+	RelatedSearchesResultNode,
 	TimeResultNode,
 	TranslateResultNode,
 	UnitConversionResultNode,
@@ -17,6 +18,7 @@ export const ResultTypes = {
 	UnitConversionResult: "CONVERSION",
 	KnowledgePanelResult: "KNOWLEDGE_PANEL",
 	NewsResult: "NEWS",
+	RelatedSearchesResult: "RELATED_SEARCHES",
 } as const;
 
 // All possible result types as a union
@@ -27,7 +29,8 @@ export type SearchResultNode =
 	| TimeResultNode
 	| UnitConversionResultNode
 	| KnowledgePanelResultNode
-	| NewsResultNode;
+	| NewsResultNode
+	| RelatedSearchesResultNode;
 
 export interface RequestOptions extends RequestInit {
 	url?: string;

packages/google-sr/src/results/index.ts

@@ -3,5 +3,6 @@ export * from "./dictionary.js";
 export * from "./knowledge-panel.js";
 export * from "./news.js";
 export * from "./organic.js";
+export * from "./related-searches.js";
 export * from "./time.js";
 export * from "./translate.js";

packages/google-sr/src/results/related-searches.ts

@@ -0,0 +1,64 @@
+import { GeneralSelector, RelatedSearchesSelector } from "google-sr-selectors";
+import {
+	type ResultParser,
+	ResultTypes,
+	type SearchResultNodeLike,
+} from "../constants.js";
+import {
+	coerceToStringOrUndefined,
+	type PartialExceptType,
+	throwNoCheerioError,
+} from "../utils.js";
+
+export interface RelatedSearchesResultNode extends SearchResultNodeLike {
+	type: typeof ResultTypes.RelatedSearchesResult;
+	queries: string[];
+}
+
+/**
+ * Parses related search queries that appear at the bottom of Google search results.
+ * This parser extracts the "Related searches" or similar related query suggestions
+ * that Google displays to help users refine their search.
+ *
+ * @example
+ * ```ts
+ * import { RelatedSearchesResult, search } from 'google-sr';
+ * const results = await search({
+ * 	query: 'nodejs frameworks',
+ * 	parsers: [RelatedSearchesResult],
+ * });
+ * // results[0].queries might contain: ["express.js", "react.js", ...]
+ * ```
+ *
+ * @returns
+ * - If noPartialResults is true, {@link RelatedSearchesResultNode} object
+ * - If noPartialResults is false, {@link PartialExceptType}<{@link RelatedSearchesResultNode}> object
+ */
+export const RelatedSearchesResult: ResultParser<RelatedSearchesResultNode> = (
+	$,
+	noPartialResults,
+) => {
+	if (!$) throwNoCheerioError("RelatedSearchesResult");
+	// usually its the last element
+	const $relatedBlock = $(GeneralSelector.block).last();
+	const $relatedQueries = $relatedBlock.find(
+		RelatedSearchesSelector.query_item,
+	);
+	const queries = [];
+	for (const query of $relatedQueries) {
+		const $el = $(query);
+		const text = coerceToStringOrUndefined(
+			$el.find(RelatedSearchesSelector.text).text(),
+		);
+		if (text) {
+			queries.push(text);
+		}
+	}
+
+	if (noPartialResults && !queries.length) return null;
+
+	return {
+		type: ResultTypes.RelatedSearchesResult,
+		queries,
+	} as RelatedSearchesResultNode;
+};

packages/google-sr/tests/results.test.ts

@@ -4,6 +4,7 @@ import {
 	KnowledgePanelResult,
 	NewsResult,
 	OrganicResult,
+	RelatedSearchesResult,
 	ResultTypes,
 	search,
 	TimeResult,
@@ -176,6 +177,25 @@ describe(
 			expect(res.timeInWords).to.be.a("string").and.not.empty;
 		});
 
+		it("Search for related searches results", async ({ expect }) => {
+			const results = await search({
+				query: "javascript frameworks",
+				parsers: [RelatedSearchesResult],
+				...GLOBAL_SEARCH_OPTIONS,
+			});
+
+			expect(results).to.be.an("array").and.have.lengthOf(1);
+			const res = results[0];
+			expect(res.type).toBe(ResultTypes.RelatedSearchesResult);
+			expect(res.queries).to.be.an("array");
+			// Verify queries are strings and not empty
+			if (res.queries) {
+				for (const query of res.queries) {
+					expect(query).to.be.a("string").and.not.empty;
+				}
+			}
+		});
+
 		it("Search for news results", async ({ expect }) => {
 			const globalSearchOptionsCopy = {
 				...GLOBAL_SEARCH_OPTIONS,