backlinks_timeseries_summary
Analyze backlink data for a domain over a specified period, grouped by day, week, month, or year. Visualize link-building progress and trends with time-series data for effective SEO strategy monitoring.
Instructions
This endpoint will provide you with an overview of backlink data for the target domain available during a period between the two indicated dates. Backlink metrics will be grouped by the time range that you define: day, week, month, or year. Data from this endpoint will be especially helpful for building time-series graphs of daily, weekly, monthly, and yearly link-building progress
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date_from | No | starting date of the time range optional field this field indicates the date which will be used as a threshold for summary data; minimum value: 2019-01-30 maximum value shouldn’t exceed the date specified in the date_to date format: "yyyy-mm-dd" example: "2021-01-01" | |
| date_to | No | ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default minimum value shouldn’t preceed the date specified in the date_from maximum value: today’s date date format: "yyyy-mm-dd" example: "2021-01-15" | |
| group_range | No | time range which will be used to group the results optional field default value: month possible values: day, week, month, year note: for day, we will return items corresponding to all dates between and including date_from and date_to; for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year for example, if you specify: "group_range": "month", "date_from": "2022-03-23", "date_to": "2022-05-13" we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31 if there is no data for a certain day/week/month/year, we will return 0 | month |
| target | Yes | domain to get data for required field a domain should be specified without https:// and www. example: "forbes.com" |
Implementation Reference
- The BacklinksTimeseriesSummaryTool class that implements the core handler logic for the 'backlinks_timeseries_summary' tool, including schema definition via getParams(), description, and the handle() method that calls the DataForSEO backlinks timeseries summary API.export class BacklinksTimeseriesSummaryTool extends BaseTool { constructor(private client: DataForSEOClient) { super(client); } getName(): string { return 'backlinks_timeseries_summary'; } getDescription(): string { return `This endpoint will provide you with an overview of backlink data for the target domain available during a period between the two indicated dates. Backlink metrics will be grouped by the time range that you define: day, week, month, or year. Data from this endpoint will be especially helpful for building time-series graphs of daily, weekly, monthly, and yearly link-building progress`; } getParams(): z.ZodRawShape { return { target: z.string().describe(`domain to get data for required field a domain should be specified without https:// and www. example: "forbes.com"`), date_from: z.string().describe(`starting date of the time range optional field this field indicates the date which will be used as a threshold for summary data; minimum value: 2019-01-30 maximum value shouldn’t exceed the date specified in the date_to date format: "yyyy-mm-dd" example: "2021-01-01"`).optional(), date_to: z.string().describe(`ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default minimum value shouldn’t preceed the date specified in the date_from maximum value: today’s date date format: "yyyy-mm-dd" example: "2021-01-15"`).optional(), group_range: z.string().optional().describe(`time range which will be used to group the results optional field default value: month possible values: day, week, month, year note: for day, we will return items corresponding to all dates between and including date_from and date_to; for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year for example, if you specify: "group_range": "month", "date_from": "2022-03-23", "date_to": "2022-05-13" we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31 if there is no data for a certain day/week/month/year, we will return 0`).default('month') }; } async handle(params: any): Promise<any> { try { const response = await this.client.makeRequest('/v3/backlinks/timeseries_summary/live', 'POST', [{ target: params.target, date_from: params.date_from, date_to: params.date_to, group_range: params.group_range }]); return this.validateAndFormatResponse(response); } catch (error) { return this.formatErrorResponse(error); } } }
- Zod schema definition for the tool parameters in getParams().getParams(): z.ZodRawShape { return { target: z.string().describe(`domain to get data for required field a domain should be specified without https:// and www. example: "forbes.com"`), date_from: z.string().describe(`starting date of the time range optional field this field indicates the date which will be used as a threshold for summary data; minimum value: 2019-01-30 maximum value shouldn’t exceed the date specified in the date_to date format: "yyyy-mm-dd" example: "2021-01-01"`).optional(), date_to: z.string().describe(`ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default minimum value shouldn’t preceed the date specified in the date_from maximum value: today’s date date format: "yyyy-mm-dd" example: "2021-01-15"`).optional(), group_range: z.string().optional().describe(`time range which will be used to group the results optional field default value: month possible values: day, week, month, year note: for day, we will return items corresponding to all dates between and including date_from and date_to; for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year for example, if you specify: "group_range": "month", "date_from": "2022-03-23", "date_to": "2022-05-13" we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31 if there is no data for a certain day/week/month/year, we will return 0`).default('month') }; }
- src/core/modules/backlinks/backlinks-api.module.ts:29-62 (registration)The BacklinksApiModule registers the BacklinksTimeseriesSummaryTool instance in its getTools() method, mapping it by name to its description, params schema, and handler.getTools(): Record<string, ToolDefinition> { const tools = [ new BacklinksTool(this.dataForSEOClient), new BacklinksAnchorTool(this.dataForSEOClient), new BacklinksBulkBacklinksTool(this.dataForSEOClient), new BacklinksBulkNewLostReferringDomainsTool(this.dataForSEOClient), new BacklinksBulkNewLostBacklinksTool(this.dataForSEOClient), new BacklinksBulkRanksTool(this.dataForSEOClient), new BacklinksBulkReferringDomainsTool(this.dataForSEOClient), new BacklinksBulkSpamScoreTool(this.dataForSEOClient), new BacklinksCompetitorsTool(this.dataForSEOClient), new BacklinksDomainIntersectionTool(this.dataForSEOClient), new BacklinksDomainPagesSummaryTool(this.dataForSEOClient), new BacklinksDomainPagesTool(this.dataForSEOClient), new BacklinksPageIntersectionTool(this.dataForSEOClient), new BacklinksReferringDomainsTool(this.dataForSEOClient), new BacklinksReferringNetworksTool(this.dataForSEOClient), new BacklinksSummaryTool(this.dataForSEOClient), new BacklinksTimeseriesNewLostSummaryTool(this.dataForSEOClient), new BacklinksTimeseriesSummaryTool(this.dataForSEOClient), new BacklinksBulkPagesSummaryTool(this.dataForSEOClient), new BacklinksFiltersTool(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/backlinks/backlinks-api.module.ts:22-22 (registration)Import statement for the BacklinksTimeseriesSummaryTool.import { BacklinksTimeseriesSummaryTool } from './tools/backlinks-timeseries-summary.tool.js';
- src/core/modules/backlinks/backlinks-api.module.ts:48-48 (registration)Instantiation of the BacklinksTimeseriesSummaryTool in the tools array.new BacklinksTimeseriesSummaryTool(this.dataForSEOClient),