Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DataForSeoClient
✓ import { DataForSeoClient } from 'dataforseo-client'
✗ const DataForSeoClient = require('dataforseo-client').DataForSeoClient
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
✓ import type { SerpGoogleOrganicLiveRequest } from 'dataforseo-client'
✗ import { 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.
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();
Debug
Known issues
breakingDataForSEO'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.fixMigrate 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.
affects: All versions of dataforseo-client used with DataForSEO API v2
gotchaDataForSEO 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.fixEnsure 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.
affects: >=1.0.0
gotchaDataForSEO 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.fixImplement 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.
affects: >=1.0.0
gotchaMany 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.fixAlways 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Request failed with status code 401
Invalid or missing API credentials (username/password) were provided during client initialization. This indicates an authentication failure.
fixVerify 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
One or more parameters in your API request body are invalid, missing, or the overall request body format is incorrect for the target endpoint.
fixThoroughly 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
You have exceeded the API's rate limit for the given endpoint within the specified time window.
fixImplement 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')
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.
fixEnsure 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.
Audit
Dependencies
No dependency data recorded yet.