Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

fix(volumes): make DataForSEO return usable numbers for niche prompts (#11)

Gökhan Geyikdca64e530303
diff --git a/server/src/lib/dataforseo-codes.js b/server/src/lib/dataforseo-codes.js
new file mode 100644
index 000000000..b31c4cb59
--- /dev/null
+++ b/server/src/lib/dataforseo-codes.js
@@ -0,0 +1,63 @@
+/**
+ * Map our internal region / language codes to DataForSEO's numeric location_code
+ * and ISO language code expected by the Google Ads search_volume endpoint.
+ *
+ * https://docs.dataforseo.com/v3/keywords_data/google_ads/locations/
+ */
+
+const REGION_TO_LOCATION_CODE = {
+ US: 2840,
+ GB: 2826,
+ CA: 2124,
+ AU: 2036,
+ DE: 2276,
+ FR: 2250,
+ IT: 2380,
+ ES: 2724,
+ NL: 2528,
+ SE: 2752,
+ CH: 2756,
+ TR: 2792,
+ JP: 2392,
+ BR: 2076,
+ IN: 2356,
+ KR: 2410,
+ MX: 2484,
+ SG: 2702,
+ AE: 2784,
+};
+
+const LANGUAGE_PASSTHROUGH = new Set([
+ 'en',
+ 'de',
+ 'fr',
+ 'es',
+ 'tr',
+ 'ja',
+ 'pt',
+ 'hi',
+ 'ko',
+ 'it',
+ 'nl',
+ 'sv',
+ 'ar',
+]);
+
+/**
+ * @param {string|null|undefined} region ISO 3166-1 alpha-2 (e.g. 'US', 'TR')
+ * @returns {number|undefined} DataForSEO numeric location code, or undefined if no mapping
+ */
+export function regionToLocationCode(region) {
+ if (!region) return undefined;
+ return REGION_TO_LOCATION_CODE[region.toUpperCase()];
+}
+
+/**
+ * @param {string|null|undefined} language ISO 639-1 (e.g. 'en', 'tr')
+ * @returns {string|undefined} DataForSEO-compatible language code, or undefined
+ */
+export function languageToCode(language) {
+ if (!language) return undefined;
+ const lower = language.toLowerCase();
+ return LANGUAGE_PASSTHROUGH.has(lower) ? lower : undefined;
+}
diff --git a/server/src/routes/volumes.js b/server/src/routes/volumes.js
index e67343f3d..d9cebedc0 100644
--- a/server/src/routes/volumes.js
+++ b/server/src/routes/volumes.js
@@ -3,6 +3,7 @@ import { generateObject } from 'ai';
import { z } from 'zod';
import { resolveModel } from '../lib/ai-provider.js';
import { getSearchVolumes } from '../lib/dataforseo.js';
+import { regionToLocationCode, languageToCode } from '../lib/dataforseo-codes.js';
import { requireFeature, enforceVolumeQuota, getVolumeQuotaStatus, PlanLimitError } from '../lib/plan-guard.js';
import supabaseAdmin from '../config/supabase.js';
@@ -29,29 +30,39 @@ const intentKeywordSchema = z.object({
.array(
z
.string()
- .describe('A short, Google-searchable keyword phrase (2-5 words)'),
+ .describe(
+ 'A short Google head term — 1 to 3 words, category-level, measurable Google Ads volume',
+ ),
)
.length(5)
.describe(
- 'Five high-volume Google search keywords that capture the same intent as the prompt',
+ 'Five broad, high-volume Google head terms that capture the category the prompt belongs to',
),
});
const INTENT_SYSTEM_PROMPT = `You are a keyword research expert. Given an AI search prompt, you must:
1. Determine the primary search intent (comparison, how-to, what-is, best-top, vs-review, recommendation, or problem-solving).
-2. Generate exactly 5 short keyword phrases (2-5 words each) that a user would type into Google when searching for the same topic.
+2. Generate exactly 5 short HEAD keywords that a user would type into Google when researching the same category.
+
+CRITICAL: Output HEAD terms, NOT long-tail variants. Google Ads only returns search volume for keywords with measurable demand — long-tail strings like "best portable motion control for travel 2026" return 0. Drop modifiers and surface the underlying noun phrases.
Rules:
-- Keywords must be generic — no brand names.
-- Keywords should be realistic, high-volume Google search queries.
-- Each keyword must be unique and cover a slightly different angle of the same topic.
-- Use lowercase only.
-- Think about what real users actually type into Google's search bar.
+- 1 to 3 words per keyword (strict). Never more than 4.
+- Generic, category-level. No brand names, no years, no superlatives ("best", "top") unless they are part of the natural head term.
+- Lowercase only.
+- Each of the 5 keywords must capture a different angle of the same category.
+- Think "what category does this prompt belong to?" → then list the broadest searchable terms in that category.
+
+Example A — prompt: "What are the best tools for managing remote teams?"
+- Intent: best-top
+- Keywords: ["project management software", "team collaboration tools", "remote work software", "team management apps", "online collaboration platform"]
-Example: For the prompt "What are the best tools for managing remote teams?"
+Example B — prompt: "best portable motion control for travel 2026"
- Intent: best-top
-- Keywords: ["best remote team tools", "remote team management software", "tools for remote teams", "remote work management", "top remote collaboration tools"]`;
+- Keywords: ["camera slider", "motion control camera", "video stabilizer", "camera dolly", "time lapse equipment"]
+
+Notice: NO "best", NO "2026", NO "for travel". Strip modifiers, keep the category nouns.`;
function mapVolumeRow(saved) {
return {
@@ -130,6 +141,25 @@ router.post('/analyze', requireFeature('prompt_volumes'), async (req, res) => {
.json({ error: 'promptId and promptText are required' });
}
+ let resolvedLocationCode = locationCode;
+ let resolvedLanguageCode = languageCode;
+ if (resolvedLocationCode == null || resolvedLanguageCode == null) {
+ const { data: brandRow } = await supabaseAdmin
+ .from('prompts')
+ .select('prompt_sets!inner(brands!inner(region, language))')
+ .eq('id', promptId)
+ .maybeSingle();
+ const brand = brandRow?.prompt_sets?.brands;
+ if (brand) {
+ if (resolvedLocationCode == null) {
+ resolvedLocationCode = regionToLocationCode(brand.region);
+ }
+ if (resolvedLanguageCode == null) {
+ resolvedLanguageCode = languageToCode(brand.language);
+ }
+ }
+ }
+
let intent;
let keywords;
@@ -162,8 +192,8 @@ router.post('/analyze', requireFeature('prompt_volumes'), async (req, res) => {
promptId,
keywords,
intent,
- locationCode,
- languageCode,
+ resolvedLocationCode,
+ resolvedLanguageCode,
);
if (orgId) {
@@ -217,6 +247,29 @@ router.post(
}
const promptIds = prompts.map((p) => p.promptId);
+
+ // Resolve DataForSEO location/language from the brand the prompts belong to,
+ // unless the caller explicitly passed an override in the request body.
+ let resolvedLocationCode = locationCode;
+ let resolvedLanguageCode = languageCode;
+ if (resolvedLocationCode == null || resolvedLanguageCode == null) {
+ const { data: brandRow } = await supabaseAdmin
+ .from('prompts')
+ .select('prompt_sets!inner(brands!inner(region, language))')
+ .in('id', promptIds)
+ .limit(1)
+ .maybeSingle();
+ const brand = brandRow?.prompt_sets?.brands;
+ if (brand) {
+ if (resolvedLocationCode == null) {
+ resolvedLocationCode = regionToLocationCode(brand.region);
+ }
+ if (resolvedLanguageCode == null) {
+ resolvedLanguageCode = languageToCode(brand.language);
+ }
+ }
+ }
+
let existingMap = {};
if (!force) {
@@ -264,8 +317,8 @@ router.post(
promptId,
keywords,
intent,
- locationCode,
- languageCode,
+ resolvedLocationCode,
+ resolvedLanguageCode,
);
results.push(mapVolumeRow(saved));
} catch (err) {
@@ -316,6 +369,24 @@ router.post('/refresh', requireFeature('prompt_volumes'), async (req, res) => {
return res.status(400).json({ error: 'brandId is required' });
}
+ let resolvedLocationCode = locationCode;
+ let resolvedLanguageCode = languageCode;
+ if (resolvedLocationCode == null || resolvedLanguageCode == null) {
+ const { data: brand } = await supabaseAdmin
+ .from('brands')
+ .select('region, language')
+ .eq('id', brandId)
+ .maybeSingle();
+ if (brand) {
+ if (resolvedLocationCode == null) {
+ resolvedLocationCode = regionToLocationCode(brand.region);
+ }
+ if (resolvedLanguageCode == null) {
+ resolvedLanguageCode = languageToCode(brand.language);
+ }
+ }
+ }
+
const { data: promptSets } = await supabaseAdmin
.from('prompt_sets')
.select('id')
@@ -357,8 +428,8 @@ router.post('/refresh', requireFeature('prompt_volumes'), async (req, res) => {
row.prompt_id,
row.keywords,
row.intent,
- locationCode,
- languageCode,
+ resolvedLocationCode,
+ resolvedLanguageCode,
);
results.push(mapVolumeRow(saved));
} catch (err) {