# How Keyword Locations Support the Retrieval of Regional Search Data in Open-SEO

> Discover how Open-SEO leverages keyword locations to efficiently retrieve regional search data, routing queries to the correct API for optimal results.

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

---

**Open-SEO uses a centralized location table in [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts) to map country codes to specific DataForSEO endpoints, automatically routing keyword queries to either the Labs or Google Ads API based on regional availability.**

Open-SEO leverages a comprehensive location catalog to translate user-selected regions into precise API endpoints for accurate keyword metrics. By analyzing the [`keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/keyword-locations.ts) module according to the every-app/open-seo source code, we can see how the system resolves markets, handles multilingual regions, and selects the appropriate data provider. This architecture ensures that regional search data retrieval is both accurate and efficient across 190+ supported countries.

## Mapping Location Codes to Data Providers

The foundation of regional search retrieval lies in the provider selection logic that determines which DataForSEO endpoint serves a specific country.

### Provider Selection Logic

The `getKeywordDataProvider()` function (lines 2727-2734) implements the routing decision between **DataForSEO Labs** (covering 94 countries) and **Google Ads** (serving remaining regions). This function checks whether a location code exists in the master set and whether it is excluded from Labs coverage:

```ts
export function getKeywordDataProvider(locationCode: number): KeywordDataProvider {
  return LOCATION_CODES.has(locationCode) && !LABS_LOCATION_CODES.has(locationCode)
    ? "google_ads"
    : "labs";
}

```

When a location code is present in `LOCATION_CODES` but absent from `LABS_LOCATION_CODES`, the system routes the request to the Google Ads endpoint. Otherwise, it defaults to the Labs API for comprehensive keyword metrics.

### The Location Catalog Structure

The `LOCATION_OPTIONS` array (starting at line 66) defines an immutable catalog where each entry represents a country with the following structure:

- `code`: The numeric DataForSEO location_code
- `label`: Human-readable country name
- `shortLabel`: ISO-style short code (e.g., "US")
- `languageCode`: Default language for that region
- `googleAdsOnly`: Optional flag indicating Labs does not support this country

The system derives `LABS_LOCATION_OPTIONS` (lines 672-674) by filtering this array to include only entries supported by the Labs API, enabling efficient UI rendering and validation.

## Resolving Markets and Default Languages

When processing keyword retrieval requests, Open-SEO must reconcile user-specified parameters with project defaults to form a complete market definition.

### Market Resolution Logic

The `resolveMarket()` function (lines 708-718) merges optional request arguments with project configuration to determine the final location and language codes:

```ts
export function resolveMarket(
  args: { locationCode?: number; languageCode?: string },
  project: { locationCode: number; languageCode: string },
): { locationCode: number; languageCode: string } {
  const locationCode = args.locationCode ?? project.locationCode;
  const languageCode =
    args.languageCode ??
    (locationCode === project.locationCode
      ? project.languageCode
      : getLanguageCode(locationCode));
  return { locationCode, languageCode };
}

```

If the request omits a location code, the function uses the project's default. When a location is specified without a language, it automatically retrieves the default language for that country via `getLanguageCode()` (lines 696-698).

### Handling Labs-Only Constraints

For tools requiring strictly Labs data, `resolveLabsMarket()` (lines 744-758) enforces fallback logic. When a project's default location is not supported by Labs, it automatically switches to `DEFAULT_LOCATION_CODE = 2840` (line 22), ensuring consistent data availability.

## Managing Regional Language Options

Accurate regional search data requires proper language attribution, particularly for multilingual countries.

### Multi-Language Location Support

The system defines available languages in `LANGUAGE_OPTIONS` (lines 541-670) and identifies multilingual regions through `MULTI_LANGUAGE_LOCATIONS` (lines 777-798). The `getLanguageOptions()` function (lines 805-812) filters the master language list to return only relevant options for a given location code:

```ts
export function getLanguageOptions(
  locationCode: number,
): readonly (typeof LANGUAGE_OPTIONS)[number][] {
  const codes = new Set(
    MULTI_LANGUAGE_LOCATIONS[locationCode] ?? [getLanguageCode(locationCode)],
  );
  return LANGUAGE_OPTIONS.filter((language) => codes.has(language.code));
}

```

This prevents UI clutter and ensures API requests use valid language-location combinations accepted by DataForSEO.

### Validation Helpers

Before issuing API calls, Open-SEO validates parameters using `isSupportedLocationCode()`, `isLabsLocationCode()`, and `isSupportedLanguageCode()` (lines 666-668). These guards prevent costly API rejections by verifying that codes exist in the respective master lists.

## Practical Implementation Examples

### Determining the API Endpoint for a Selected Country

To route a keyword query correctly, resolve the provider based on the location code:

```ts
import { getKeywordDataProvider, LOCATION_OPTIONS } from "./shared/keyword-locations";

const country = LOCATION_OPTIONS.find(o => o.shortLabel === "DE")!; // Germany
const provider = getKeywordDataProvider(country.code);
console.log(provider); // "labs"

```

### Resolving Markets with Automatic Language Detection

When handling custom location requests without explicit language codes:

```ts
import { resolveMarket } from "./shared/keyword-locations";

const project = { locationCode: 2840, languageCode: "en" }; // US default
const request = { locationCode: 2356 }; // India (no language supplied)

const market = resolveMarket(request, project);
console.log(market);
// → { locationCode: 2356, languageCode: "en" }  // default language for India

```

### Retrieving Language Options for Multilingual Regions

For countries supporting multiple languages, filter available options:

```ts
import { getLanguageOptions } from "./shared/keyword-locations";

const options = getLanguageOptions(2356); // India
options.forEach(l => console.log(`${l.code}: ${l.label}`));
// → en: English
// → hi: Hindi

```

## Summary

- **Centralized routing**: The [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts) module serves as the single source of truth for mapping countries to DataForSEO endpoints.
- **Intelligent provider selection**: `getKeywordDataProvider()` automatically chooses between Labs and Google Ads APIs based on regional availability.
- **Market resolution**: `resolveMarket()` handles complex fallback logic for locations and languages, ensuring valid API parameters.
- **Multi-language support**: The system identifies multilingual regions and filters language options to prevent invalid API requests.
- **Validation layers**: Helper functions verify location and language codes before expensive API calls, improving reliability and performance.

## Frequently Asked Questions

### How does Open-SEO determine which API provider to use for a specific country?

Open-SEO checks the location code against two sets in [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts): `LOCATION_CODES` and `LABS_LOCATION_CODES`. If the code exists in the master set but not in the Labs-specific set, `getKeywordDataProvider()` returns `"google_ads"`; otherwise, it returns `"labs"`. This logic ensures that the 94 countries supported by DataForSEO Labs receive comprehensive metrics, while remaining countries fall back to Google Ads data.

### What happens if a user requests keyword data for a location not supported by DataForSEO Labs?

When a request specifies a Labs-unsupported location, the `getKeywordDataProvider()` function automatically routes the query to the Google Ads endpoint. Additionally, for tools that strictly require Labs data, the `resolveLabsMarket()` function forces a fallback to the United States (location code 2840) to ensure data availability, preventing API errors while maintaining analytics continuity.

### How does the system handle language selection for multilingual countries?

For countries listed in `MULTI_LANGUAGE_LOCATIONS` (such as India or Canada), the `getLanguageOptions()` function retrieves all valid language codes for that region from the master `LANGUAGE_OPTIONS` catalog. If no specific language is requested, `resolveMarket()` automatically assigns the country's default language code via `getLanguageCode()`, ensuring that keyword retrieval targets the correct linguistic market without manual intervention.

### Can I validate a location code before making an API request?

Yes, Open-SEO provides `isSupportedLocationCode()` to verify that a numeric code exists in the location catalog, and `isLabsLocationCode()` to confirm Labs API availability. For language validation, use `isSupportedLanguageCode()` (lines 666-668). These functions prevent costly API rejections by catching invalid parameters at the application layer before transmitting requests to DataForSEO.