keywords_data_dataforseo_trends_subregion_interests
Analyze keyword popularity trends across specific locations and time periods to inform SEO strategies and content planning.
Instructions
This endpoint will provide you with location-specific keyword popularity data from DataForSEO Trends
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| location_name | No | full name of the location optional field in format "Country" example: United Kingdom | |
| keywords | Yes | keywords the maximum number of keywords you can specify: 5 | |
| type | No | dataforseo trends type | web |
| 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" | |
| 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 |
Implementation Reference
- The handle method implements the core logic of the tool. It makes a POST request to the DataForSEO API endpoint '/v3/keywords_data/dataforseo_trends/subregion_interests/live' with the input parameters wrapped in an array, then validates and formats the response or handles errors.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); } }
- Defines the input schema using Zod shapes for parameters: location_name, keywords, type, date_from, date_to, 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) along with other tools and registers them by name into a record used for tool definitions, including description, params, and handler wrappers.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), }, }), {}); }