DataForSEO API Client

Common errors

• Error: Request failed with status code 401

  cause Invalid or missing API credentials (username/password) were provided during client initialization. This indicates an authentication failure.
  fix Verify that your `DATAFORSEO_USERNAME` (your DataForSEO account email) and `DATAFORSEO_PASSWORD` (the specific API password from your dashboard) are correct and correctly passed to the `DataForSeoClient` constructor. Ensure they have not been swapped.

• Error: Request failed with status code 400

  cause One or more parameters in your API request body are invalid, missing, or the overall request body format is incorrect for the target endpoint.
  fix Thoroughly review the DataForSEO API documentation for the specific endpoint you are calling to confirm all required parameters are present, correctly named, and adhere to the expected data types and formats (e.g., `language_code`, `location_code`, `keyword`).

• Error: Request failed with status code 429

  cause You have exceeded the API's rate limit for the given endpoint within the specified time window.
  fix Implement a delay or a retry mechanism with exponential backoff between consecutive requests. If persistent, consider contacting DataForSEO support to discuss potential increases in your rate limits.

• TypeError: Cannot read properties of undefined (reading 'google')

  cause This typically occurs when attempting to access a nested API section (e.g., `client.serp.google`) on an `undefined` or incorrectly initialized client object. This can happen if the `DataForSeoClient` constructor failed or the client object was not properly assigned.
  fix Ensure that `const client = new DataForSeoClient(username, password);` executes without errors and that the `client` variable holds a valid instance. Verify that the full access path to the API endpoint (e.g., `client.serp.google.organic.live.post`) accurately reflects the library's structure.

Warnings

• breaking DataForSEO's underlying API v2 has been deprecated and will cease to be supported as of May 5, 2026. This client library (`dataforseo-client` v2.x.x) is specifically designed to interact with DataForSEO API v3. Users migrating from older DataForSEO client libraries or direct API v2 calls must update their code to conform to API v3 specifications, which involves significant changes in endpoint paths, request bodies, and response structures.
  Fix: Migrate your DataForSEO account and API usage to API v3. The `dataforseo-client` package is fully compatible with API v3. Review the DataForSEO v3 Migration Guide for detailed changes in endpoint paths, request bodies, and response structures.
• gotcha DataForSEO API uses Basic Authentication, requiring an API login and password. These are distinct from your general account login and password, and the API password is automatically generated. Providing incorrect credentials will result in authentication failures.
  Fix: Ensure you are using the specific API login (your email) and the unique API password obtained from the 'API Access' tab within your DataForSEO dashboard. Do not use your regular DataForSEO account password for API authentication.
• gotcha DataForSEO APIs enforce rate limits per endpoint. Exceeding these limits can lead to HTTP 429 'Too Many Requests' responses, temporary blocking, or failed requests. The `X-RateLimit-Limit` and `X-RateLimit-Remaining` HTTP headers in responses indicate your current rate limit status.
  Fix: Implement robust error handling for HTTP 429 status codes and incorporate retry mechanisms with exponential backoff. Monitor the `X-RateLimit-Remaining` header to dynamically adjust your request frequency and avoid hitting limits.
• gotcha Many DataForSEO API operations, particularly for extensive data requests, utilize a 'task-based' asynchronous workflow. This involves posting a task, then polling a separate endpoint for the task's status, and finally retrieving the results once the task is complete. Directly expecting an immediate, complete response from an initial `POST` request for such endpoints will lead to incomplete data or errors.
  Fix: Always consult the DataForSEO API documentation for each specific endpoint to determine if it uses a 'Live' (immediate response) or 'Task-based' (asynchronous) delivery method. For task-based endpoints, implement the full workflow: `task_post` to create the task, `task_ready` to check status, and `task_get` to retrieve final results.

Install

• npm install dataforseo-client npm
• yarn add dataforseo-client yarn
• pnpm add dataforseo-client pnpm

Imports

• DataForSeoClient
  wrong:

  const DataForSeoClient = require('dataforseo-client').DataForSeoClient

  correct:

  import { DataForSeoClient } from 'dataforseo-client'

  The primary class for instantiating the client. All API sections (e.g., `serp`, `keywordsData`) are accessed as properties of an instance of this class.
• SerpGoogleOrganicLiveRequest
  wrong:

  import { SerpGoogleOrganicLiveRequest } from 'dataforseo-client'

  correct:

  import type { SerpGoogleOrganicLiveRequest } from 'dataforseo-client'

  Imports the TypeScript type definition for a specific request payload, providing type safety when constructing API request objects. Use `import type` for type-only imports to avoid runtime overhead.
• SerpGoogleOrganicLiveResponse

  import type { SerpGoogleOrganicLiveResponse } from 'dataforseo-client'

  Imports the TypeScript type definition for a specific API response structure, enabling type-safe handling of the data returned by an endpoint. Use `import type` for type-only imports.

Quickstart

This quickstart demonstrates how to initialize the DataForSEO client with credentials and perform a live SERP API request for Google organic results. It illustrates how to define request payloads using imported types, handle the API response, and iterate through the results, including basic error handling.

import { DataForSeoClient } from 'dataforseo-client';
import type { SerpGoogleOrganicLiveRequest, SerpGoogleOrganicLiveResponse } from 'dataforseo-client';

// Ensure you set these environment variables or replace with actual credentials
const username = process.env.DATAFORSEO_USERNAME ?? 'YOUR_DATAFORSEO_USERNAME';
const password = process.env.DATAFORSEO_PASSWORD ?? 'YOUR_DATAFORSEO_PASSWORD';

async function runSerpLiveExample() {
  if (username === 'YOUR_DATAFORSEO_USERNAME' || password === 'YOUR_DATAFORSEO_PASSWORD') {
    console.error('ERROR: Please provide your DataForSEO API username and password. Find them at https://app.dataforseo.com/api-access.');
    return;
  }

  const client = new DataForSeoClient(username, password);

  try {
    // Define the request payload for a live Google organic SERP search
    const post_array: SerpGoogleOrganicLiveRequest[] = [
      {
        language_code: "en",
        location_code: 2840, // Example: New York, United States
        keyword: "best seo tools 2024",
        se_domain: "google.com",
        depth: 10, // Retrieve top 10 results
      },
      {
        language_code: "en",
        location_code: 2840, // Example: New York, United States
        keyword: "content marketing strategies",
        se_domain: "google.com",
        depth: 5,
      }
    ];

    // Make the API call, explicitly typing the response
    const response: SerpGoogleOrganicLiveResponse = await client.serp.google.organic.live.post(post_array);

    if (response.status_code === 20000) {
      console.log("API Call Successful. Processing results...");
      response.tasks.forEach(task => {
        if (task.result) {
          task.result.forEach(result => {
            result.items?.forEach(item => {
              if (item.type === 'organic') {
                console.log(`- Keyword: ${task.data?.keyword}`);
                console.log(`  Title: ${item.title}`);
                console.log(`  URL: ${item.url}`);
                console.log(`  Rank: ${item.rank_absolute}\n`);
              }
            });
          });
        }
      });
    } else {
      console.error(`API Error: Status Code ${response.status_code} - ${response.status_message}`);
      console.error("API Errors:", response.errors);
    }
  } catch (error) {
    console.error("An unexpected error occurred during API call:", error);
    if (error instanceof Error) {
      console.error(error.message);
    }
  }
}

runSerpLiveExample();