How Keyword Location Targeting Works in Open SEO: Default SERP Locations Explained

Keyword location targeting in Open SEO uses DataForSEO numeric location codes to fetch market-specific SERP data, defaulting to location code 2840 (United States) and language code "en" when no location is specified.

Open SEO is an open-source SEO platform that integrates with the DataForSEO Labs API to retrieve keyword rankings and search volume. The system relies on keyword location targeting to ensure that SERP (Search Engine Results Page) data reflects specific geographic markets, using standardized numeric codes to identify countries and regions. When projects do not explicitly define a target market, the platform automatically falls back to a default location to maintain data consistency.

How Keyword Location Targeting Works

Location Codes and DataForSEO Integration

The targeting mechanism centers on numeric location codes defined by DataForSEO. Each code represents a specific geographic market; for example, 2840 corresponds to the United States. These codes are exported from src/shared/keyword-locations.ts and used throughout the application to scope API requests. When initiating keyword research or rank tracking, the system must provide both a locationCode and a languageCode to the DataForSEO Labs API.

Validation and Resolution Logic

Before making API calls, the system validates location codes using utility functions such as isSupportedLocationCode and isLabsLocationCode, both defined in src/shared/keyword-locations.ts. Server-side resolution occurs in src/server/lib/market.ts, where the resolveLocationAndLanguage function checks for missing parameters. If a request lacks a location code, the function substitutes the default value and pairs it with the appropriate language code.

Default SERP Locations and Fallback Behavior

The platform defines a default SERP location for all keyword-related operations. In src/shared/keyword-locations.ts, the constant DEFAULT_LOCATION_CODE is set to 2840, which maps to the United States. When a project or API request does not specify a location, this value is automatically applied.

The default language code paired with this location is "en" (English). This pairing ensures that SERP data retrieved for the default location is semantically aligned with English search queries. The fallback logic is implemented across multiple layers:

• Server-side: src/server/lib/market.ts resolves missing location and language parameters before sending requests to DataForSEO.
• Client-side: The usePreferredKeywordLocation hook in src/client/features/keywords/hooks/usePreferredKeywordLocation.ts selects the project's configured location or defaults to 2840 if none is set.

Implementation in the Codebase

Several key files manage the location targeting logic:

• src/shared/keyword-locations.ts: Contains DEFAULT_LOCATION_CODE, location-to-language mappings via getLanguageCode, and validation helpers isSupportedLocationCode and isLabsLocationCode.
• src/server/lib/market.ts: Handles server-side market resolution and fallback logic using resolveLocationAndLanguage.
• src/client/features/keywords/hooks/usePreferredKeywordLocation.ts: React hook for UI components to access the current location context.
• src/types/schemas/keywords.ts: Zod schemas that validate optional locationCode and languageCode fields in API requests.

Code Examples

Client-side location selection using the React hook:

import { usePreferredKeywordLocation } from '@/client/features/keywords/hooks/usePreferredKeywordLocation';

function LocationBadge({ projectId }: { projectId: string }) {
  const { locationCode, languageCode } = usePreferredKeywordLocation(projectId);

  return (
    <span>
      {locationCode} – {languageCode}
    </span>
  );
}

Server-side resolution with fallback defaults:

import { resolveLocationAndLanguage, DEFAULT_LOCATION_CODE } from '@/shared/keyword-locations';

function getMarket({ locationCode, languageCode }: { locationCode?: number; languageCode?: string }) {
  const { locationCode: loc, languageCode: lang } = resolveLocationAndLanguage(
    { locationCode, languageCode },
    { locationCode: DEFAULT_LOCATION_CODE, languageCode: 'en' }
  );

  // Pass resolved codes to DataForSEO request
  return { loc, lang };
}

Summary

• Keyword location targeting relies on DataForSEO numeric codes (e.g., 2840 for the United States) to fetch geographically specific SERP data.
• The default SERP location is the United States (location code 2840) with language code "en", defined in src/shared/keyword-locations.ts.
• Fallback logic in src/server/lib/market.ts and the usePreferredKeywordLocation hook ensure that missing location parameters default to these values.
• Validation functions like isSupportedLocationCode prevent invalid location codes from reaching the DataForSEO API.

Frequently Asked Questions

What is the default location code for SERP data in Open SEO?

The default location code is 2840, which represents the United States. This constant is exported from src/shared/keyword-locations.ts as DEFAULT_LOCATION_CODE and is used whenever a project or request does not specify a target market.

How does Open SEO handle missing location parameters?

When location or language parameters are omitted, the system invokes resolveLocationAndLanguage (defined in src/shared/keyword-locations.ts and consumed by src/server/lib/market.ts) to substitute the defaults: location code 2840 and language code "en". This ensures that every API request to DataForSEO includes valid geographic targeting.

What language code pairs with the default location?

The default location code 2840 (United States) pairs with the language code "en" (English). The getLanguageCode function in src/shared/keyword-locations.ts provides this mapping, and the client-side hook usePreferredKeywordLocation applies it automatically when falling back to the default.

Where is the location validation logic defined?

Validation helpers such as isSupportedLocationCode and isLabsLocationCode are defined in src/shared/keyword-locations.ts. Additionally, src/types/schemas/keywords.ts contains Zod schemas that validate optional locationCode and languageCode fields in incoming API requests, ensuring only supported codes are processed.

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