backlinks_bulk_ranks

Instructions

Implementation Reference

• src/core/modules/backlinks/tools/backlinks-bulk-ranks.tool.ts:47-57 (handler)

  The main execution logic of the tool: makes a POST request to DataForSEO's /v3/backlinks/bulk_ranks/live endpoint with targets and rank_scale, validates/formats response or handles error.

  async handle(params: any): Promise<any> {
    try {
      const response = await this.client.makeRequest('/v3/backlinks/bulk_ranks/live', 'POST', [{
        targets: params.targets,
        rank_scale: params.rank_scale        
      }]);
      return this.validateAndFormatResponse(response);
    } catch (error) {
      return this.formatErrorResponse(error);
    }
  }

• src/core/modules/backlinks/tools/backlinks-bulk-ranks.tool.ts:18-45 (schema)

  Input schema definition using Zod: required 'targets' array of strings (domains/subdomains/pages), optional 'rank_scale' string defaulting to 'one_thousand'.

    getParams(): z.ZodRawShape {
      return {
        targets: z.array(z.string()).describe(`domains, subdomains or webpages to get rank for
  required field
  you can set up to 1000 domains, subdomains or webpages
  the domain or subdomain should be specified without https:// and www.
  the page should be specified with absolute URL (including http:// or https://)
  example:
  "targets": [
  "forbes.com",
  "cnn.com",
  "bbc.com",
  "yelp.com",
  "https://www.apple.com/iphone/",
  "https://ahrefs.com/blog/",
  "ibm.com",
  "https://variety.com/",
  "https://stackoverflow.com/",
  "www.trustpilot.com"
  ]`),
        rank_scale: z.string().optional().describe(`defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
  optional field
  you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale
  possible values:
  one_hundred — rank values are displayed on a 0–100 scale
  one_thousand — rank values are displayed on a 0–1000 scale`).default('one_thousand')
      };
    }

• src/core/modules/backlinks/backlinks-api.module.ts:31-64 (registration)

  Tool registration in BacklinksApiModule's getTools(): instantiates BacklinksBulkRanksTool among others and registers it using its getName(), getDescription(), getParams(), and wraps handle() as the tool 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/tools/backlinks-bulk-ranks.tool.ts:10-12 (registration)

  The getName() method providing the exact tool name 'backlinks_bulk_ranks' used during registration.

  getName(): string {
    return 'backlinks_bulk_ranks';
  }