keywords_data_dataforseo_trends_subregion_interests
Analyze location-specific keyword popularity trends over time. Retrieve data for up to 5 keywords across web, news, or ecommerce categories, with customizable date ranges and preset time periods.
Instructions
This endpoint will provide you with location-specific keyword popularity data from DataForSEO Trends
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date_from | No | starting date of the time range if you don’t specify this field, the current day and month of the preceding year will be used by default minimal value for the web type: 2004-01-01 minimal value for other types: 2008-01-01 date format: "yyyy-mm-dd" example: "2019-01-15" | |
| date_to | No | ending date of the time range if you don’t specify this field, the today’s date will be used by default date format: "yyyy-mm-dd" example: "2019-01-15" | |
| keywords | Yes | keywords the maximum number of keywords you can specify: 5 | |
| location_name | No | full name of the location optional field in format "Country" example: United Kingdom | |
| time_range | No | preset time ranges if you specify date_from or date_to parameters, this field will be ignored when setting a task | past_7_days |
| type | No | dataforseo trends type | web |
Implementation Reference
- The core handler function that sends a POST request to the DataForSEO Trends subregion interests endpoint with the provided parameters and handles the response or error.async handle(params: any): Promise<any> { try { const response = await this.dataForSEOClient.makeRequest('/v3/keywords_data/dataforseo_trends/subregion_interests/live', 'POST', [{ location_name: params.location_name, keywords: params.keywords, type: params.type, date_from: params.date_from, date_to: params.date_to, time_range: params.time_range, }]); return this.validateAndFormatResponse(response); } catch (error) { return this.formatErrorResponse(error); } }
- The Zod schema defining the input parameters for the tool, including location_name, keywords, type, date_from, date_to, and time_range.getParams(): z.ZodRawShape { return { location_name: z.string().nullable().default(null).describe(`full name of the location optional field in format "Country" example: United Kingdom`), keywords: z.array(z.string()).describe(`keywords the maximum number of keywords you can specify: 5`), type: z.enum(['web', 'news', 'ecommerce']).default('web').describe(`dataforseo trends type`), date_from: z.string().optional().describe(`starting date of the time range if you don’t specify this field, the current day and month of the preceding year will be used by default minimal value for the web type: 2004-01-01 minimal value for other types: 2008-01-01 date format: "yyyy-mm-dd" example: "2019-01-15"`), date_to: z.string().optional() .describe( `ending date of the time range if you don’t specify this field, the today’s date will be used by default date format: "yyyy-mm-dd" example: "2019-01-15"`), time_range: z.enum(['past_4_hours', 'past_day', 'past_7_days', 'past_30_days', 'past_90_days', 'past_12_months', 'past_5_years']) .default('past_7_days') .describe( `preset time ranges if you specify date_from or date_to parameters, this field will be ignored when setting a task`), }; }
- The getTools() method in KeywordsDataApiModule instantiates the DataForSeoTrendsSubregionInterestsTool (line 15 relative to start) and registers it in the tools record using the tool's getName(), along with description, params, and wrapped handler.getTools(): Record<string, ToolDefinition> { const tools = [ new GoogleAdsSearchVolumeTool(this.dataForSEOClient), new DataForSeoTrendsDemographyTool(this.dataForSEOClient), new DataForSeoTrendsSubregionInterestsTool(this.dataForSEOClient), new DataForSeoTrendsExploreTool(this.dataForSEOClient), new GoogleTrendsCategoriesTool(this.dataForSEOClient), new GoogleTrendsExploreTool(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), }, }), {}); } }
- src/core/modules/keywords-data/tools/dataforseo-trends/dataforseo-trends-subregion-interests.tool.ts:10-12 (registration)The getName() method returns the exact tool name used for registration.getName(): string { return 'keywords_data_dataforseo_trends_subregion_interests'; }