open-seo Framework and Library: DataForSEO Client Integration Explained

open-seo does not implement its own SEO engine; instead, it relies entirely on the DataForSEO platform via the official dataforseo-client NPM package, wrapped in a TypeScript abstraction layer that adds billing metering and type-safe helpers.

The every-app/open-seo repository provides a server-side SEO toolkit that delegates all heavy lifting to the DataForSEO API. Rather than maintaining native ranking algorithms or crawling infrastructure, the codebase functions as a billing-aware bridge between your application and DataForSEO's commercial data services.

The Core Dependency: DataForSEO Client

According to the package.json manifest, open-seo declares a hard dependency on dataforseo-client version 2.0.19. This official library handles low-level HTTP transport, authentication, and request serialization to DataForSEO's REST endpoints.

Open-seo then wraps this client in a custom architecture located under src/server/lib/dataforseo/. The wrapper provides three value-added features:

• Structured endpoint groups organized by business function (SERP, keywords, Lighthouse, etc.)
• Billing metering through a meter helper that tracks credit consumption
• TypeScript type safety imported directly from the dataforseo-client package

Architecture of the SEO Client

Central Client Factory (src/server/lib/dataforseo/client.ts)

The entry point for all SEO operations is the createDataforseoClient function exported from src/server/lib/dataforseo/client.ts. This factory accepts a customer context object (for billing tracking) and returns a structured client object exposing the following endpoint groups:

• business
• backlinks
• keywords
• domain
• serp
• labs
• lighthouse
• aiSearch

Each group maps to a dedicated submodule in the same directory. Before and after every API invocation, the internal meterDataforseoCall helper records usage credits against the customer context, ensuring accurate billing for DataForSEO's metered API access.

Endpoint Modules

The client delegates actual API calls to specialized modules under src/server/lib/dataforseo/:

• serp.ts – Implements fetchLiveSerp and fetchRankCheckSerp for real-time and rank-tracking SERP data
• labs.ts – Wraps keyword research endpoints including fetchKeywordIdeas and fetchKeywordOverview
• google-ads.ts – Provides Google Ads-specific endpoints for regions not covered by the Labs API
• lighthouse.ts – Exposes fetchLighthouseResult for performance audits via DataForSEO's Lighthouse integration
• ai.ts – Contains AI-search utilities such as fetchLlmMentionsSearch

These modules import their request and response types from the dataforseo-client package, ensuring the TypeScript compiler validates payloads against DataForSEO's official schema.

Implementation Example

Below demonstrates how the billing-aware client is instantiated and used to fetch keyword ideas, live SERP data, and Lighthouse reports:

import { createDataforseoClient } from '@/server/lib/dataforseo/client';
import { getCustomerContext } from '@/server/billing/subscription';

// Obtain a billing-aware customer context
const customer = await getCustomerContext(/* … */);

// Build the DataForSEO client
const seo = createDataforseoClient(customer);

// 1️⃣ Fetch keyword ideas (Google Ads endpoint)
const keywordIdeas = await seo.keywords.adsIdeas({
  keywords: ['open seo'],
  locationCode: 2840, // United States
});

// 2️⃣ Run a live SERP fetch
const liveSerp = await seo.serp.live({
  target: 'https://example.com',
  searchEngine: 'google',
});

// 3️⃣ Retrieve Lighthouse performance data
const lighthouse = await seo.lighthouse.live({
  target: 'https://example.com',
});

In this pattern, createDataforseoClient injects the customer context into each call site, allowing meterDataforseoCall to reconcile API usage against subscription credits before returning results to the application layer.

Summary

• open-seo uses the official dataforseo-client library (v2.0.19) rather than custom SEO algorithms
• The central factory in src/server/lib/dataforseo/client.ts exposes grouped endpoints via createDataforseoClient
• Billing metering is enforced through the meterDataforseoCall wrapper that tracks DataForSEO credit consumption
• Specialized modules in src/server/lib/dataforseo/* provide type-safe access to SERP, keyword, Lighthouse, and AI search endpoints

Frequently Asked Questions

What SEO library does open-seo use under the hood?

open-seo relies on the DataForSEO platform and its official dataforseo-client NPM package. All ranking data, keyword research, and audit functionality is fetched remotely from DataForSEO's API rather than computed locally.

Does open-seo implement its own web crawling or ranking algorithms?

No. The repository contains no native crawling logic or proprietary ranking formulas. Instead, it functions as a billing-aware proxy that wraps DataForSEO's commercial data services in TypeScript helpers for type safety and account metering.

How does open-seo track billing for SEO API calls?

The codebase implements a meterDataforseoCall helper inside src/server/lib/dataforseo/client.ts that intercepts every request. This utility records credit consumption before and after each DataForSEO API invocation, ensuring usage aligns with the customer's subscription tier.

Which DataForSEO endpoints are supported by open-seo?

The client exposes eight major endpoint groups: business, backlinks, keywords, domain, serp, labs, lighthouse, and aiSearch. Each maps to specific DataForSEO REST endpoints for tasks ranging from live SERP fetching to AI-driven mention tracking.

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