# How to Use OpenSEO to Identify Organic Search Opportunities: A Complete Guide

> Discover organic search opportunities with OpenSEO. This guide shows how to merge GSC, GA4, and DataForSEO data to find high-volume, low-competition keywords. Boost your SEO strategy today.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-20

---

**OpenSEO identifies organic search opportunities by merging Google Search Console impressions, Google Analytics 4 organic sessions, and DataForSEO Labs keyword data into a ranked list of high-volume, low-competition keywords.**

OpenSEO is a self-hosted SEO platform that surfaces actionable search opportunities through its **MCP (Multi-Channel Provider) Tools** architecture. The system correlates your existing organic performance data with third-party keyword metrics to find untapped ranking potential. This guide walks through the complete workflow, implementation details, and four ways to invoke the analysis.

## How OpenSEO's Search Opportunity Pipeline Works

The platform follows a six-stage pipeline to transform raw data into prioritized keyword recommendations:

| Step | Component | Source Location |
|------|-----------|---------------|
| 1 | Request ingestion via CLI, API, or Web UI | `web/src/routes/api/…` |
| 2 | MCP tool dispatches to `get_search_opportunities` | [`src/server/mcp/tools/google-analytics-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/google-analytics-tools.ts) |
| 3 | DataForSEO Labs API call with location validation | [`src/server/mcp/tools/dataforseo-research-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/dataforseo-research-tools.ts) |
| 4 | Credit consumption and 7-day result caching | [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) |
| 5 | Aggregation of GSC, GA, and keyword metrics | [`src/server/features/sam/samChatTools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/sam/samChatTools.ts) |
| 6 | Table presentation with opportunity scoring | [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) |

The **opportunity score** is computed as a heuristic combining high search volume, low keyword difficulty, and evidence of existing organic traction. This surfaces keywords where you already have some presence but could capture significantly more traffic with targeted optimization.

## Prerequisites: Data Sources for Organic Search Opportunities

To generate meaningful results, your OpenSEO project must have three integrations configured:

- **Google Search Console** — provides impression data showing which queries already trigger your site in search results. See [`docs/SELF_HOSTING_GOOGLE_SEARCH_CONSOLE.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_GOOGLE_SEARCH_CONSOLE.md) for setup instructions.

- **Google Analytics 4** — supplies "organic" session counts to validate which keywords drive actual visits. Configuration details are in [`docs/SELF_HOSTING_GOOGLE_ANALYTICS.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_GOOGLE_ANALYTICS.md).

- **DataForSEO API key** — enables keyword-level volume, CPC, and difficulty metrics. Self-hosted deployments pass costs directly through using the `DATAFORSEO_API_KEY` environment variable (gated in [`src/shared/selfhost-checks.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts)).

All DataForSEO calls require **ISO 3166-1 alpha-2 country codes** and language codes. The canonical mapping lives in [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts) with the `isSupportedLocationCode` validator.

## Method 1: CLI Command for Search Opportunities

The built-in `openseo` CLI provides the fastest entry point for one-off analyses. The command forwards to the MCP tool registration in [`src/server/mcp/tools/google-analytics-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/google-analytics-tools.ts).

```bash

# List projects to locate your project ID

openseo list-projects

# Run the organic search opportunity analysis

openseo get-search-opportunities \
  --projectId <project-id> \
  --keywords "organic coffee, sustainable tea, fair-trade chocolate"

```

The CLI automatically handles authentication and project resolution before invoking the DataForSEO pipeline.

## Method 2: Direct HTTP API Call

For automation or custom integrations, POST directly to the MCP tools endpoint at line 357 of [`src/server/mcp/tools/google-analytics-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/google-analytics-tools.ts):

```bash
curl -X POST https://<your-openseo-host>/api/mcp/tools/get_search_opportunities \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "projectId": "<project-id>",
        "keywords": ["organic coffee","sustainable tea","fair-trade chocolate"]
      }'

```

This returns the aggregated opportunity data immediately. The backend merges GA organic sessions with DataForSEO metrics before responding.

## Method 3: Web UI Dashboard

The MCP Dashboard provides visual exploration of search opportunities:

1. Navigate to **MCP → Search Opportunities**
2. Select your project and enter comma-separated seed keywords
3. Click **Run** to execute the analysis

The results table displays: **Keyword**, **Avg Vol**, **CPC**, **Difficulty**, **GA Organic Sessions**, and computed **Opportunity Score**. Columns are populated by the aggregation logic in [`src/server/features/sam/samChatTools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/sam/samChatTools.ts).

## Method 4: Programmatic Node.js/TypeScript Access

The `@openseo/mcp-client` package wraps HTTP calls into typed methods:

```typescript
import { createMcpClient } from '@openseo/mcp-client';

const client = createMcpClient({
  baseUrl: 'https://<your-openseo-host>',
  token: '<your-token>',
});

const result = await client.callTool('get_search_opportunities', {
  projectId: '<project-id>',
  keywords: ['organic coffee', 'sustainable tea', 'fair-trade chocolate'],
});

console.log(result);
// → Array of opportunity objects with scoring metadata

```

This matches the exact API surface used by the CLI and web UI, ensuring consistent results across all interfaces.

## Understanding the Response: Search Opportunity Data Structure

Each opportunity object follows this schema:

```json
[
  {
    "keyword": "organic coffee",
    "searchVolume": 6200,
    "cpcUsd": 1.45,
    "difficulty": 32,
    "gaOrganicSessions": 340,
    "gscImpressions": 1120,
    "opportunityScore": 0.78
  }
]

```

- **searchVolume** — monthly average from DataForSEO Labs
- **cpcUsd** — cost-per-click indicating commercial intent
- **difficulty** — 0-100 ranking difficulty estimate
- **gaOrganicSessions** — your verified organic traffic for this keyword
- **gscImpressions** — how often Google displayed your site for this query
- **opportunityScore** — composite ranking (higher = better investment target)

Keywords with high `opportunityScore` values represent **existing organic traction** plus **expandable volume** — the ideal candidates for content updates or new page creation.

## Cost Optimization: Task Queues and Caching

OpenSEO implements two cost-control mechanisms from [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts):

- **Task queues** — For "live" SERP requests, DataForSEO's task queue reduces costs to approximately 30% of standard live pricing while respecting rate limits.

- **7-day caching** — DataForSEO lookups including Google Business categories are cached in [`src/server/mcp/tools/local-seo-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/local-seo-tools.ts). Repeated opportunity analyses for the same keywords return cached results without consuming additional credits.

Self-hosted deployments pay DataForSEO directly with no markup. The [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) module tracks usage for hosted instances, preventing balance depletion through pre-call credit checks.

## Location and Language Code Requirements

Every DataForSEO call requires validated location parameters. The helper [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts) enforces supported combinations:

```typescript
// Valid call example
{
  "location_code": 2840,  // United States
  "language_code": "en"   // English
}

```

Invalid codes return validation errors before API calls consume credits. The mapping supports 50+ countries with their primary languages.

## Summary

- **OpenSEO identifies organic search opportunities** by correlating GSC impressions, GA4 organic sessions, and DataForSEO keyword metrics through the `get_search_opportunities` MCP tool.

- **Four invocation methods** are available: CLI (`openseo get-search-opportunities`), HTTP API (`/api/mcp/tools/get_search_opportunities`), Web UI dashboard, and programmatic TypeScript client.

- **Key source files** include [`google-analytics-tools.ts`](https://github.com/every-app/open-seo/blob/main/google-analytics-tools.ts) (tool definition), [`dataforseo-research-tools.ts`](https://github.com/every-app/open-seo/blob/main/dataforseo-research-tools.ts) (API wrapper), [`keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/keyword-locations.ts) (validation), and [`samChatTools.ts`](https://github.com/every-app/open-seo/blob/main/samChatTools.ts) (scoring logic).

- **Cost efficiency** comes from 7-day caching and optional task queues for live SERP data.

- **Prerequisites** are GSC property connection, GA4 organic tracking, and valid DataForSEO API credentials.

## Frequently Asked Questions

### What data sources does OpenSEO require for search opportunity analysis?

OpenSEO requires **Google Search Console** for impression data, **Google Analytics 4** for organic session validation, and **DataForSEO Labs** for keyword volume, CPC, and difficulty metrics. All three must be configured before the `get_search_opportunities` tool returns complete results. GSC and GA setup guides are in [`docs/SELF_HOSTING_GOOGLE_SEARCH_CONSOLE.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_GOOGLE_SEARCH_CONSOLE.md) and [`docs/SELF_HOSTING_GOOGLE_ANALYTICS.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_GOOGLE_ANALYTICS.md).

### How does OpenSEO calculate the opportunity score?

The opportunity score is a heuristic computed in [`src/server/features/sam/samChatTools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/sam/samChatTools.ts) that weights high search volume, low keyword difficulty, and existing organic traffic evidence. Keywords already generating GA sessions and GSC impressions but with untapped volume potential receive the highest scores. The 0-1 normalized output enables direct priority ranking.

### What are the costs for running search opportunity analyses?

Self-hosted OpenSEO deployments pay DataForSEO directly at their published API rates with no platform markup. Hosted instances use an internal credit system defined in [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) that converts raw USD costs. Results are cached for 7 days in [`src/server/mcp/tools/local-seo-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/local-seo-tools.ts), preventing duplicate charges for repeated keyword lookups. Live SERP requests can use task queues at approximately 30% of standard costs.

### Can I use OpenSEO search opportunities without connecting Google Analytics?

You can invoke `get_search_opportunities` without GA connection, but the returned data will lack the **gaOrganicSessions** field. This severely degrades the opportunity score accuracy, as the system cannot distinguish between keywords with proven traffic performance versus speculative targets. Full value requires all three data sources.