keywords_data_dataforseo_trends_demography
Analyze keyword popularity by age and gender demographics for up to 5 terms, using DataForSEO Trends data. Specify location, time range, and data source type (web, news, ecommerce) to generate actionable insights for targeted audience strategies.
Instructions
This endpoint will provide you with the demographic breakdown (by age and gender) of keyword popularity per each specified term based on DataForSEO Trends data
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
- src/core/modules/keywords-data/tools/dataforseo-trends/dataforseo-trends-demography.tool.ts:50-64 (handler)The main handler function that makes a POST request to the DataForSEO Trends Demography API 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/demography/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); } }
- src/core/modules/keywords-data/tools/dataforseo-trends/dataforseo-trends-demography.tool.ts:18-48 (schema)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`), }; }
- Tool registration in the KeywordsDataApiModule where the DataForSeoTrendsDemographyTool is instantiated and added to the tools registry using its getName() as the key.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), }, }), {}); }