How to Integrate OpenSEO with the DataForSEO API: Complete Configuration Guide

Integrating OpenSEO with the DataForSEO API requires Base64-encoding your DataForSEO credentials and setting them as the DATAFORSEO_API_KEY environment variable, which enables the backend to route keyword research, backlink analysis, and rank tracking requests through DataForSEO's pay-as-you-go service.

The every-app/open-seo repository is a full-stack SEO analytics platform that uses DataForSEO as its primary data provider. Configuring this connection allows both cloud-hosted and self-hosted deployments to access real-time SEO intelligence while the application handles task queuing, error management, and cost calculations transparently.

Architecture Overview

OpenSEO abstracts the DataForSEO API behind a unified server layer. When a user requests backlink data or keyword rankings, the backend constructs a task envelope, submits it to DataForSEO's queue, and polls for results.

Key components include:

• DataForSEO Client – Handles authentication and HTTP transport to DataForSEO endpoints. Located in [src/lib/dataforseo-client.ts](https://github.com/every-app/open-seo/blob/main/src/lib/dataforseo-client.ts).
• Self-Host Validation – Runtime checks ensure the DATAFORSEO_API_KEY is present and correctly formatted before any paid request executes. See [src/shared/selfhost-checks.ts](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts).
• Billing Logic – Converts raw DataForSEO USD rates to hosted credit costs using a markup factor. Implemented in [src/shared/billing.ts](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts).
• Task Functions – Server functions like [src/serverFunctions/backlinks.ts](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts) orchestrate DataForSEO tasks for specific features.

Prerequisites

Before configuring the integration, ensure you have:

• A DataForSEO account with API access (new accounts receive complimentary credits).
• Your DataForSEO email address and password ready for Base64 encoding.
• Access to environment configuration files for your deployment method.

Configuration Steps

1. Generate Your API Key

DataForSEO uses HTTP Basic Authentication requiring a Base64-encoded string of your credentials. Combine your email and password with a colon separator, then encode:

echo -n 'your-email@example.com:your-password' | base64

The output (e.g., YWJjQGV4YW1wbGUuY29tOnBhc3N3b3Jk) is your DATAFORSEO_API_KEY.

2. Configure Environment Variables

Add the encoded key to your environment. For self-hosted deployments, edit .env.example and rename it to .env:

# .env

DATAFORSEO_API_KEY=YWJjQGV4YW1wbGUuY29tOnBhc3N3b3JkMTIz

For Docker deployments, see [web/content/docs/self-hosting/docker.md](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/docker.md) for specific injection instructions.

3. Verify the Connection

Test your configuration without consuming credits using the built-in whoami command. This validates authentication and displays your remaining DataForSEO balance:

npm run cli whoami

This command executes the logic in [src/server/mcp/tools/whoami.ts](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts), which queries the DataForSEO /v3/serp/google/locations endpoint to confirm connectivity.

Usage Examples

Environment Configuration

# .env

DATAFORSEO_API_KEY=base64:encoded_string_here
DATABASE_URL=postgresql://...

Programmatic Backlink Request

The following excerpt from [src/serverFunctions/backlinks.ts](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts) demonstrates how OpenSEO submits tasks to DataForSEO:

import { dataForSeoClient } from '../lib/dataforseo-client';

export async function getBacklinks(projectId: string, domain: string) {
  const payload = [{
    target: domain,
    mode: 'asap',
    filters: ['do_follow', 'active']
  }];
  
  const response = await dataForSeoClient.post('/backlinks/live', payload);
  
  // Poll for task completion and handle 20000 status codes (success)
  return await pollTaskResults(response.data.task_id);
}

Checking Account Usage

Self-hosted administrators can monitor DataForSEO consumption using the utility script:

npx ts-node scripts/dataforseo-account-usage.ts

This script is defined in [scripts/dataforseo-account-usage.ts](https://github.com/every-app/open-seo/blob/main/scripts/dataforseo-account-usage.ts) and returns your current credit balance and recent usage statistics.

Cost Structure and Billing

DataForSEO operates on a pay-as-you-go model where each API task has a specific USD cost. OpenSEO handles billing differently depending on your deployment:

• Self-Hosted: You pay DataForSEO directly at raw rates. The application passes through costs without markup.
• Cloud-Hosted: OpenSEO applies a 28% markup (multiplier of 1.28) to raw DataForSEO rates. The conversion occurs in [src/shared/billing.ts](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts):

export function rawToHostedCost(rawUsd: number): number {
  const MARKUP = 1.28; // 28% OpenSEO markup
  return Math.round(rawUsd * MARKUP * 100) / 100;
}

Summary

• DataForSEO provides the underlying SEO data for keyword research, rank tracking, and backlink analysis in OpenSEO.
• The integration requires setting DATAFORSEO_API_KEY as a Base64-encoded email:password string in your environment.
• Self-host checks in src/shared/selfhost-checks.ts validate the key before executing paid requests.
• Use the whoami CLI command to verify connectivity without spending credits.
• Self-hosted users pay DataForSEO directly, while cloud users purchase credits through OpenSEO at a marked-up rate.

Frequently Asked Questions

Do I need a separate DataForSEO account to self-host OpenSEO?

Yes. Self-hosted deployments require you to create your own DataForSEO account and provide your personal API credentials via the DATAFORSEO_API_KEY environment variable. You are billed directly by DataForSEO for all API consumption. The cloud-hosted version manages DataForSEO access internally; you simply purchase OpenSEO credits.

What format must the DATAFORSEO_API_KEY use?

The key must be a Base64-encoded string of your DataForSEO login email and password separated by a colon (email:password). For example, user@example.com:password123 becomes dXNlckBleGFtcGxlLmNvbTpwYXNzd29yZDEyMw==. The application decodes this in the DataForSEO client to construct the Basic Auth header.

How can I check my DataForSEO credit balance without making a paid request?

Run the whoami command via the CLI (npm run cli whoami). This executes a lightweight API call to DataForSEO's locations endpoint that authenticates your credentials but does not deduct credits from your account. Alternatively, use the scripts/dataforseo-account-usage.ts script to fetch detailed balance and usage history.

Is there a markup on DataForSEO costs for OpenSEO?

Only for the cloud-hosted version. Self-hosted users pay DataForSEO's raw rates directly. The hosted SaaS applies approximately a 28% markup on top of DataForSEO's base pricing to cover infrastructure and management costs, as implemented in the billing conversion functions.

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