How to Use the DataForSEO API Client in OpenSEO: A Complete Guide

OpenSEO provides a typed, billing-aware wrapper around the official dataforseo-client SDK, exposing a createDataforseoClient factory that instantiates API clients with built-in rate limiting and error handling.

OpenSEO (every-app/open-seo) ships with a thin, typed wrapper around the DataForSEO API located in src/server/lib/dataforseo/. This wrapper transforms the official SDK into a billing-contextual client that handles authentication, rate limiting, and response validation automatically. Understanding how to use the DataForSEO API client in OpenSEO enables you to fetch SERP data, keyword metrics, and backlink intelligence within the framework's server-side architecture.

Initializing the DataForSEO Client

The entry point for all DataForSEO operations is the createDataforseoClient factory function exported from src/server/lib/dataforseo/client.ts. This function requires a BillingCustomerContext object containing the current user's billing plan and quota information.

import { createDataforseoClient } from "@/server/lib/dataforseo";

const dataforseo = createDataforseoClient(billingCustomer);

The factory returns a typed client object that groups DataForSEO modules under properties like serp, labs, and googleAds. According to the OpenSEO source code, this design allows the client to respect per-plan API quotas while providing full IntelliSense for available endpoints.

Calling DataForSEO API Endpoints

Once initialized, the client exposes typed methods that mirror the official DataForSEO API structure. Each module provides methods that accept request payloads and return Promise-wrapped responses validated through Zod schemas.

Fetching SERP Data

The SERP module in src/server/lib/dataforseo/serp.ts provides access to live search results. Use the google.organic.live method to retrieve real-time organic rankings:

const live = await dataforseo.serp.google.organic.live({
  target: "example.com",
  keywords: [{ keyword: "open seo", location_code: 2840 }],
});

Accessing Labs API Features

For keyword research and content intelligence, the Labs API wrapper in src/server/lib/dataforseo/labs.ts exposes endpoints like related_keywords.live:

const related = await dataforseo.labs.google.related_keywords.live({
  keyword: "open seo",
  country: "us",
});

Retrieving Google Ads Metrics

The Google Ads module (src/server/lib/dataforseo/google-ads.ts) provides CPC and search volume data through the keywords_data.get method:

const ads = await dataforseo.googleAds.keywords_data.get({
  keyword: "open seo",
  country: "us",
});

Error Handling and Response Validation

All API calls pass through the envelope helper located in src/server/lib/dataforseo/envelope.ts. The wrapAsync function translates DataForSEO error objects into a consistent { errorCode, message } shape and throws typed exceptions when status_code !== 200. This ensures that downstream code receives standardized error objects rather than raw SDK responses.

Rate Limiting and Billing Awareness

The wrapper implements billing-aware throttling using constants defined in src/server/lib/dataforseo/shared.ts. The MAX_TASKS_PER_POST value determines batch sizes to prevent hitting API rate limits. Because the createDataforseoClient function receives the user's BillingCustomerContext, the client automatically adjusts request volume based on the specific plan's quota limits.

Real-World Usage in Workflows

OpenSEO's production workflows demonstrate the typical server-side pattern. In src/server/workflows/RankCheckWorkflow.ts, the client is instantiated per-request and passed to service functions:

const client = createDataforseoClient(billingCustomer);
const results = await client.serp.google.organic.live(...);

Complete server function example:

import { createDataforseoClient } from "@/server/lib/dataforseo";

export async function getKeywordInsights(billingCustomer) {
  const dfs = createDataforseoClient(billingCustomer);

  // Fetch live SERP data
  const serp = await dfs.serp.google.organic.live({
    target: "example.com",
    keywords: [{ keyword: "open seo", location_code: 2840 }],
  });

  // Fetch related keywords from Labs API
  const related = await dfs.labs.google.related_keywords.live({
    keyword: "open seo",
    country: "us",
  });

  // Fetch Google Ads volume/CPC
  const ads = await dfs.googleAds.keywords_data.get({
    keyword: "open seo",
    country: "us",
  });

  return { serp, related, ads };
}

For React Server Components or TanStack Server Functions:

import { createDataforseoClient } from "@/server/lib/dataforseo";
import { getBillingCustomer } from "@/server/lib/auth-session";

export async function fetchSerpForPage(pageUrl: string) {
  const billingCustomer = await getBillingCustomer();
  const dfs = createDataforseoClient(billingCustomer);

  const response = await dfs.serp.google.organic.live({
    target: pageUrl,
    keywords: [{ keyword: "next-js seo", location_code: 2840 }],
  });

  return response;
}

Summary

• Factory Pattern: Import createDataforseoClient from @/server/lib/dataforseo and pass a BillingCustomerContext to instantiate the client.
• Typed Modules: Access SERP, Labs, and Google Ads endpoints through typed properties like serp.google.organic.live.
• Automatic Validation: All responses pass through Zod validation and error normalization via src/server/lib/dataforseo/envelope.ts.
• Quota Management: The client respects billing plan limits using MAX_TASKS_PER_POST from src/server/lib/dataforseo/shared.ts to batch requests appropriately.
• Server-First Design: Initialize the client within server functions or workflows like RankCheckWorkflow.ts, never exposing credentials to the client bundle.

Frequently Asked Questions

What is the DataForSEO API client in OpenSEO?

The DataForSEO API client in OpenSEO is a typed wrapper around the official dataforseo-client SDK located in src/server/lib/dataforseo/. It provides a factory function createDataforseoClient that creates billing-aware API instances with built-in rate limiting, error handling, and Zod validation for all DataForSEO endpoints including SERP, Labs, and Google Ads data.

How does the OpenSEO wrapper handle API rate limits?

The wrapper respects rate limits through the MAX_TASKS_PER_POST constant defined in src/server/lib/dataforseo/shared.ts. When the createDataforseoClient function receives a BillingCustomerContext, it uses the plan's quota information to batch tasks appropriately, preventing requests from exceeding the user's API allowance or DataForSEO's posting limits.

Which DataForSEO endpoints are available through the OpenSEO client?

As implemented in every-app/open-seo, the wrapper exposes three main modules: SERP (src/server/lib/dataforseo/serp.ts) for search results, Labs (src/server/lib/dataforseo/labs.ts) for keyword research and content ideas, and Google Ads (src/server/lib/dataforseo/google-ads.ts) for CPC and volume data. Each module provides typed methods that correspond to DataForSEO's live API endpoints.

How are errors handled when calling DataForSEO endpoints?

All API calls are wrapped by the envelope helper in src/server/lib/dataforseo/envelope.ts. The wrapAsync function intercepts responses, validates them against expected schemas using Zod, and translates DataForSEO error objects into standardized { errorCode, message } shapes. When the API returns a status_code !== 200, the wrapper throws a typed exception that can be caught and handled by your application logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}