{"id":15585,"library":"dataforseo-client","title":"DataForSEO API Client","description":"The `dataforseo-client` is a comprehensive TypeScript API client designed to facilitate interaction with the DataForSEO API. It currently stands at version 2.0.23 and provides a streamlined interface to 12 distinct API sections, including AI Optimization, SERP, Keywords Data, Domain Analytics, and Backlinks. This client abstracts the complexities of raw HTTP requests and response parsing, offering developers ready-to-use methods for both live (synchronous HTTP request/response) and task-based (asynchronous, multi-step task submission and retrieval) API calls. Built from an OpenAPI specification, it ships with full TypeScript type definitions for an enhanced development experience. While a specific release cadence isn't published, its frequent updates and versioning suggest active development. A key advantage is its ability to handle DataForSEO's extensive data ecosystem through a consistent, type-safe programming interface, allowing users to focus on data utilization rather than integration specifics.","status":"active","version":"2.0.23","language":"javascript","source_language":"en","source_url":"https://github.com/dataforseo/TypeScriptClient","tags":["javascript","typescript"],"install":[{"cmd":"npm install dataforseo-client","lang":"bash","label":"npm"},{"cmd":"yarn add dataforseo-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add dataforseo-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for instantiating the client. All API sections (e.g., `serp`, `keywordsData`) are accessed as properties of an instance of this class.","wrong":"const DataForSeoClient = require('dataforseo-client').DataForSeoClient","symbol":"DataForSeoClient","correct":"import { DataForSeoClient } from 'dataforseo-client'"},{"note":"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.","wrong":"import { SerpGoogleOrganicLiveRequest } from 'dataforseo-client'","symbol":"SerpGoogleOrganicLiveRequest","correct":"import type { SerpGoogleOrganicLiveRequest } from 'dataforseo-client'"},{"note":"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.","symbol":"SerpGoogleOrganicLiveResponse","correct":"import type { SerpGoogleOrganicLiveResponse } from 'dataforseo-client'"}],"quickstart":{"code":"import { DataForSeoClient } from 'dataforseo-client';\nimport type { SerpGoogleOrganicLiveRequest, SerpGoogleOrganicLiveResponse } from 'dataforseo-client';\n\n// Ensure you set these environment variables or replace with actual credentials\nconst username = process.env.DATAFORSEO_USERNAME ?? 'YOUR_DATAFORSEO_USERNAME';\nconst password = process.env.DATAFORSEO_PASSWORD ?? 'YOUR_DATAFORSEO_PASSWORD';\n\nasync function runSerpLiveExample() {\n  if (username === 'YOUR_DATAFORSEO_USERNAME' || password === 'YOUR_DATAFORSEO_PASSWORD') {\n    console.error('ERROR: Please provide your DataForSEO API username and password. Find them at https://app.dataforseo.com/api-access.');\n    return;\n  }\n\n  const client = new DataForSeoClient(username, password);\n\n  try {\n    // Define the request payload for a live Google organic SERP search\n    const post_array: SerpGoogleOrganicLiveRequest[] = [\n      {\n        language_code: \"en\",\n        location_code: 2840, // Example: New York, United States\n        keyword: \"best seo tools 2024\",\n        se_domain: \"google.com\",\n        depth: 10, // Retrieve top 10 results\n      },\n      {\n        language_code: \"en\",\n        location_code: 2840, // Example: New York, United States\n        keyword: \"content marketing strategies\",\n        se_domain: \"google.com\",\n        depth: 5,\n      }\n    ];\n\n    // Make the API call, explicitly typing the response\n    const response: SerpGoogleOrganicLiveResponse = await client.serp.google.organic.live.post(post_array);\n\n    if (response.status_code === 20000) {\n      console.log(\"API Call Successful. Processing results...\");\n      response.tasks.forEach(task => {\n        if (task.result) {\n          task.result.forEach(result => {\n            result.items?.forEach(item => {\n              if (item.type === 'organic') {\n                console.log(`- Keyword: ${task.data?.keyword}`);\n                console.log(`  Title: ${item.title}`);\n                console.log(`  URL: ${item.url}`);\n                console.log(`  Rank: ${item.rank_absolute}\\n`);\n              }\n            });\n          });\n        }\n      });\n    } else {\n      console.error(`API Error: Status Code ${response.status_code} - ${response.status_message}`);\n      console.error(\"API Errors:\", response.errors);\n    }\n  } catch (error) {\n    console.error(\"An unexpected error occurred during API call:\", error);\n    if (error instanceof Error) {\n      console.error(error.message);\n    }\n  }\n}\n\nrunSerpLiveExample();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions of dataforseo-client used with DataForSEO API v2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Invalid or missing API credentials (username/password) were provided during client initialization. This indicates an authentication failure.","error":"Error: Request failed with status code 401"},{"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`).","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.","error":"Error: Request failed with status code 400"},{"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.","cause":"You have exceeded the API's rate limit for the given endpoint within the specified time window.","error":"Error: Request failed with status code 429"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'google')"}],"ecosystem":"npm"}