How OpenSEO Manages Keyword Research and Metrics: A Deep Dive into DataForSEO Integration

OpenSEO delegates all keyword research to DataForSEO, automatically routing requests to either the Labs API (for search volume, keyword difficulty, and search intent) or the Google Ads API (volume-only) based on location support.

OpenSEO's keyword research and metrics system is built around location-aware API routing that ensures users receive the richest available data for their target markets. Rather than implementing proprietary keyword databases, the platform leverages DataForSEO's infrastructure while adding intelligent provider selection and robust input validation. This architecture keeps the codebase maintainable while maximizing data coverage across global markets.

How OpenSEO Routes Keyword Data Requests

Location-Based API Provider Selection

The core routing logic lives in /src/shared/keyword-locations.ts. OpenSEO maintains a static table called LOCATION_OPTIONS that maps every supported country to its DataForSEO configuration, including whether it supports the Labs API or requires fallback to Google Ads.

The getKeywordDataProvider(locationCode) function performs this selection at lines 55-63:

// Returns "labs" or "google_ads" based on location support
const provider = getKeywordDataProvider(2250); // France → "labs"
const provider = getKeywordDataProvider(2116); // Hong Kong → "google_ads"

Labs locations receive search volume, keyword difficulty scores, and search intent classification. Google Ads-only locations receive search volume only—no difficulty or intent data.

Market Resolution with Fallback Logic

OpenSEO handles three common scenarios through dedicated resolver functions:

• resolveMarket (lines 16-27): Basic merging of user overrides with project defaults
• resolveLabsMarket (lines 45-57): Forces fallback to DEFAULT_LOCATION_CODE = 2840 (United States) when the project default lacks Labs support
• resolveKeywordDataLanguage (lines 31-40): Returns requested language if supported, otherwise falls back to the country's default

This ensures keyword research requests never fail due to unsupported location-language combinations.

Validating Keyword Research Inputs

Before any API call, OpenSEO runs strict validation through three guard functions in /src/shared/keyword-locations.ts:

// Lines 42-49: Location validation
isSupportedLocationCode(code);   // Throws if country unknown
isLabsLocationCode(code);        // Checks Labs availability

// Lines 75-77: Language validation  
isSupportedLanguageCode(lang);   // Ensures DataForSEO accepts the language

These checks prevent wasted API calls and provide clear error messages to users when their market selection needs adjustment.

Fetching Keyword Metrics: Complete Workflow

Here's how the pieces connect in a production keyword research flow:

import {
  resolveLabsMarket,
  getKeywordDataProvider,
  resolveKeywordDataLanguage,
} from '~/shared/keyword-locations';
import { fetchKeywordData } from '~/serverFunctions/serp-locations';

export async function getKeywordMetrics(
  locationCode: number,
  languageCode: string,
  keyword: string,
  projectDefaults: { locationCode: number; languageCode: string }
) {
  // 1. Resolve market with Labs fallback
  const market = resolveLabsMarket(
    { locationCode, languageCode },
    projectDefaults
  );
  
  // 2. Select API provider
  const provider = getKeywordDataProvider(market.locationCode);
  
  // 3. Validate and resolve language
  const lang = resolveKeywordDataLanguage(market.locationCode, market.languageCode);
  
  // 4. Build payload and execute
  const payload = {
    location_code: market.locationCode,
    language_code: lang,
    keywords: [keyword],
  };
  
  return await fetchKeywordData(provider, payload);
}

The fetchKeywordData function in /src/serverFunctions/serp-locations.ts handles the actual HTTP transport to DataForSEO's endpoints, abstracting authentication and response parsing.

Storing Keywords for Ongoing Tracking

OpenSEO persists user-selected keywords through /src/shared/saved-keyword-tags.ts:

import { addSavedKeyword } from '~/shared/saved-keyword-tags';

await addSavedKeyword({
  projectId: 'proj_123',
  keyword: 'cloudflare workers',
  locationCode: 2840,    // United States
  languageCode: 'en',
});

These saved keywords feed into rank-tracking jobs that use the same market resolution logic from /src/shared/rank-tracking.ts. The resolveMarket and resolveLabsMarket functions are reused here, ensuring consistency between research and tracking workflows.

Optional: Google Search Console Integration

For users who connect their GSC accounts, /src/shared/gsc.ts provides supplemental metrics including click-through rate and impression data. This operates independently from DataForSEO but enriches the keyword research context with actual performance data from the user's own properties.

Summary

• Primary data source: DataForSEO platform via Labs API (full metrics) or Google Ads API (volume only)
• Provider selection: Automatic based on LOCATION_OPTIONS table in /src/shared/keyword-locations.ts
• Location fallback: Defaults to United States (code 2840) when Labs unavailable
• Language handling: Validates against supported codes, falls back to country default
• Code reuse: Same market resolvers power both keyword research and rank tracking
• Persistence: Saved keywords stored via /src/shared/saved-keyword-tags.ts for later use

Frequently Asked Questions

What metrics does OpenSEO provide for keyword research?

Labs API locations return search volume, keyword difficulty scores, and search intent classification. Google Ads-only locations return search volume without difficulty or intent data. The determination happens automatically based on the selected country.

How does OpenSEO handle unsupported countries or languages?

The resolveLabsMarket function forces a fallback to the United States (location code 2840) when the requested location lacks Labs support. For languages, resolveKeywordDataLanguage falls back to the country's default language if the requested code isn't supported—ensuring requests always succeed with valid parameters.

Can I use my own Google Search Console data in OpenSEO?

Yes. The /src/shared/gsc.ts module integrates optional Google Search Console connections, pulling actual click-through rates and impression data to supplement DataForSEO's estimates. This requires user authentication through Google's OAuth flow.

Where does OpenSEO store keywords I want to track later?

Saved keywords persist through functions in /src/shared/saved-keyword-tags.ts, which associates keywords with project IDs along with their location and language codes. These records feed directly into rank-tracking jobs using the same market resolution logic as the research interface.

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