dataforseo_labs_bulk_keyword_difficulty
Analyze the ranking difficulty of up to 1,000 keywords in one request. Determine the relative challenge of achieving top-10 organic search results for specific keywords using a logarithmic scale from 0 to 100.
Instructions
This endpoint will provide you with the Keyword Difficulty metric for a maximum of 1,000 keywords in one API request. Keyword Difficulty stands for the relative difficulty of ranking in the first top-10 organic results for the related keyword. Keyword Difficulty in DataForSEO API responses indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | Yes | target keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000 | |
| language_code | No | language code required field example: en | en |
| location_name | No | full name of the location required field in format "Country" example: United Kingdom | United States |
Implementation Reference
- The handle method that executes the core tool logic: makes a POST request to the DataForSEO Labs API endpoint '/v3/dataforseo_labs/google/bulk_keyword_difficulty/live' with keywords, location_name, and language_code parameters, then validates and formats the response or handles errors.async handle(params: any): Promise<any> { try { const response = await this.client.makeRequest('/v3/dataforseo_labs/google/bulk_keyword_difficulty/live', 'POST', [{ keywords: params.keywords, location_name: params.location_name, language_code: params.language_code }]); return this.validateAndFormatResponse(response); } catch (error) { return this.formatErrorResponse(error); } }
- Defines the Zod schema for tool input parameters: keywords (required array of strings, max 1000), location_name (string, default 'United States'), language_code (string, default 'en').getParams(): z.ZodRawShape { return { keywords: z.array(z.string()).describe(`target keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000`), location_name: z.string().default("United States").describe(`full name of the location required field in format "Country" example: United Kingdom`), language_code: z.string().default("en").describe( `language code required field example: en`), }; }
- Registers the tool (along with others) in DataForSEOLabsApi module by creating a record mapping tool.getName() to its description, params schema, and handler function.return tools.reduce((acc, tool) => ({ ...acc, [tool.getName()]: { description: tool.getDescription(), params: tool.getParams(), handler: (params: any) => tool.handle(params), }, }), {});
- Instantiates the GoogleBulkKeywordDifficultyTool class in the tools array of DataForSEOLabsApi.getTools().new GoogleBulkKeywordDifficultyTool(this.dataForSEOClient),