dataforseo_labs_google_historical_serp
Analyze historical Google SERPs to track keyword ranking changes over time, identify featured snippets, and monitor SERP feature dynamics for specific keywords and locations.
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 | |
| language_code | No | language code required field example: en | en |
| location_name | No | full name of the location required field in format "Country" example: United Kingdom | United States |
Implementation Reference
- src/core/modules/dataforseo-labs/tools/google/competitor-research/google-historical-serp.ts:35-63 (handler)Executes the tool logic: makes POST request to DataForSEO Labs Google Historical SERPs endpoint, handles full or filtered 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-33 (schema)Input schema definition using Zod for keyword, location_name, and language_code parameters.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`) }; }
- Instantiates and registers the GoogleHistoricalSERP tool (line 37) within the DataForSEOLabsApi module's tool registry, using its name, description, params, and handle method.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), }, }), {}); }