# open-seo Framework and Library: DataForSEO Client Integration Explained

> Explore the open-seo framework and its seamless integration with DataForSEO using the dataforseo-client library. Discover type-safe helpers and billing metering.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: deep-dive
- Published: 2026-06-28

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/serp.ts)** – Implements `fetchLiveSerp` and `fetchRankCheckSerp` for real-time and rank-tracking SERP data
- **[`labs.ts`](https://github.com/every-app/open-seo/blob/main/labs.ts)** – Wraps keyword research endpoints including `fetchKeywordIdeas` and `fetchKeywordOverview`
- **[`google-ads.ts`](https://github.com/every-app/open-seo/blob/main/google-ads.ts)** – Provides Google Ads-specific endpoints for regions not covered by the Labs API
- **[`lighthouse.ts`](https://github.com/every-app/open-seo/blob/main/lighthouse.ts)** – Exposes `fetchLighthouseResult` for performance audits via DataForSEO's Lighthouse integration
- **[`ai.ts`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.