dataforseo_labs_google_historical_serp
Analyze Google SERP ranking changes over time for keywords and locations to track SEO performance and featured snippet history.
Instructions
This endpoint will provide you with Google SERPs collected within the specified time frame. You will also receive a complete overview of featured snippets and other extra elements that were present within the specified dates. The data will allow you to analyze the dynamics of keyword rankings over time for the specified keyword and location.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | target keyword | |
| location_name | No | full name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada' | United States |
| language_code | No | language code required field example: en | en |
Implementation Reference
- src/core/modules/dataforseo-labs/tools/google/competitor-research/google-historical-serp.ts:35-63 (handler)The handle method that executes the tool logic: makes API request to DataForSEO Labs Google historical SERPs endpoint, processes and formats the response.
async handle(params: any): Promise<any> { try { const response = await this.client.makeRequest('/v3/dataforseo_labs/google/historical_serps/live', 'POST', [{ keyword: params.keyword, location_name: params.location_name, language_code: params.language_code }]); console.error(JSON.stringify(response)); if(defaultGlobalToolConfig.fullResponse || this.supportOnlyFullResponse()){ return this.validateAndFormatResponse(response); } else { let data = response as DataForSEOResponse; this.validateResponse(data); let result = data.items; let filteredResult = result.map(item => this.filterResponseFields(item, [ "datetime", "items.type", "items.title", "items.domain", "items.rank_absolute"])); console.error(JSON.stringify(filteredResult)); return this.formatResponse(filteredResult); } } catch (error) { return this.formatErrorResponse(error); } } - src/core/modules/dataforseo-labs/tools/google/competitor-research/google-historical-serp.ts:19-34 (schema)Zod schema defining the input parameters: keyword, location_name, language_code.
getParams(): z.ZodRawShape { return { keyword: z.string().describe(`target keyword`), location_name: z.string().default("United States").describe(`full name of the location required field in format "Country" example: United Kingdom`), language_code: z.string().default("en").describe( `language code required field example: en`) }; } - Registers the tool by instantiating GoogleHistoricalSERP and including it in the tools array, which is then mapped to tool definitions with name, description, params, and handler.
getTools(): Record<string, ToolDefinition> { const tools = [ new GoogleRankedKeywordsTool(this.dataForSEOClient), new GoogleDomainCompetitorsTool(this.dataForSEOClient), new GoogleDomainRankOverviewTool(this.dataForSEOClient), new GoogleKeywordsIdeasTool(this.dataForSEOClient), new GoogleRelatedKeywordsTool(this.dataForSEOClient), new GoogleKeywordsSuggestionsTool(this.dataForSEOClient), new GoogleHistoricalSERP(this.dataForSEOClient), new GoogleSERPCompetitorsTool(this.dataForSEOClient), new GoogleBulkKeywordDifficultyTool(this.dataForSEOClient), new GoogleSubdomainsTool(this.dataForSEOClient), new GoogleKeywordOverviewTool(this.dataForSEOClient), new GoogleTopSearchesTool(this.dataForSEOClient), new GoogleSearchIntentTool(this.dataForSEOClient), new GoogleKeywordsForSiteTool(this.dataForSEOClient), new GoogleDomainIntersectionsTool(this.dataForSEOClient), new GoogleHistoricalDomainRankOverviewTool(this.dataForSEOClient), new GooglePageIntersectionsTool(this.dataForSEOClient), new GoogleBulkTrafficEstimationTool(this.dataForSEOClient), new DataForSeoLabsFilterTool(this.dataForSEOClient), new GoogleHistoricalKeywordDataTool(this.dataForSEOClient), // Add more tools here ]; return tools.reduce((acc, tool) => ({ ...acc, [tool.getName()]: { description: tool.getDescription(), params: tool.getParams(), handler: (params: any) => tool.handle(params), }, }), {}); }