How the Local SEO Business Listings Feature Fetches Google Business Profile Questions and Answers

The local SEO business listings feature retrieves Google Business Profile Q&A data by invoking the DataForSEO API through the get_google_business_questions tool defined in src/server/mcp/tools/dataforseo-research-tools.ts, handling authentication, coordinate formatting, and structured response processing.

The every-app/open-seo repository provides a comprehensive local SEO toolkit that includes automated fetching of Google Business Profile questions and answers. This capability enables businesses to monitor customer inquiries and competitor Q&A activity programmatically. Understanding how the local SEO business listings feature fetch questions and answers reveals the integration patterns between the Multi-Channel Processor (MCP) and third-party SEO data providers.

Tool Definition and Schema Validation

The entry point for Q&A retrieval resides in src/server/mcp/tools/dataforseo-research-tools.ts at lines 727-808. The system exports getGoogleBusinessQuestionsTool, which encapsulates the business logic for fetching business questions. The tool configuration enforces strict input validation through getGoogleBusinessQuestionsInputSchema, ensuring required parameters like keyword and location coordinates are present before API invocation. The output schema defines an array of loosely-typed question objects that map to DataForSEO's response structure.

Authentication and Client Initialization

Before executing external API calls, the handler wraps operations with withMcpProjectAuth to acquire the current project's billing context (lines 889-892). This authentication layer validates project permissions and creates a DataForSEO client instance via createDataforseoClient(context.billing), establishing authenticated sessions with proper rate limiting and credential management. The client factory resides in src/server/lib/dataforseo/client.ts, centralizing API key management and request configuration for all DataForSEO interactions.

API Request Construction and Parameter Mapping

The core API interaction occurs through client.business.questionsAnswers, which accepts four critical parameters to target specific business listings:

• keyword — The business category or service term to query (e.g., "plumbing services")
• locationCoordinate — Formatted coordinates generated by formatQuestionsAnswersCoordinate(args.near)
• languageCode — Locale specification defaulting to the project language if omitted
• depth — Result limit specifying the number of Q&A rows to retrieve (default 20)

Coordinate Formatting Utility

The system converts latitude/longitude objects into DataForSEO's required string format using coordinate utilities. For example, coordinates { lat: 40.7128, lng: -74.0060 } are transformed into the API-specific format before injection into the request payload.

Response Processing and Structured Output

Upon API resolution (lines 999-1008), the tool constructs a human-readable header indicating the fetch volume (e.g., "Fetched X Google Business Q&A rows") and renders results as a markdown-style table via formatMcpTable. The response payload bifurcates into two distinct formats:

• meta — Project navigation metadata for UI state management and breadcrumb generation
• structuredContent — Raw questions array containing question_text, answer_text, and metadata fields for downstream analytics or automated reporting workflows

Implementation Example

While the MCP runtime handles actual tool invocation, developers can replicate the core logic using the following pattern:

import { createDataforseoClient } from '@/src/server/lib/dataforseo/client';
import { formatQuestionsAnswersCoordinate } from '@/src/server/mcp/tools/coordinate-utils';

// Example arguments (normally provided by the MCP UI)
const args = {
  keyword: 'plumbing services',
  near: { lat: 40.7128, lng: -74.0060 },
  languageCode: 'en',
  depth: 20,
  projectId: 'proj_123',
};

async function fetchBusinessQandA() {
  const client = createDataforseoClient(/* billing context */);
  const questions = await client.business.questionsAnswers({
    keyword: args.keyword,
    locationCoordinate: formatQuestionsAnswersCoordinate(args.near),
    languageCode: args.languageCode,
    depth: args.depth,
  });

  console.log(`Fetched ${questions.length} Q&A rows`);
  console.table(questions); // raw array of {question_text, answer_text, …}
}

Summary

• The get_google_business_questions tool in src/server/mcp/tools/dataforseo-research-tools.ts serves as the primary interface for Q&A retrieval
• Authentication relies on withMcpProjectAuth and createDataforseoClient to manage secure API access
• Coordinate formatting is required to convert geographic inputs into DataForSEO's expected format
• The system returns dual-format responses containing both human-readable markdown tables and structured JSON arrays
• Depth control allows customization of result volumes with a default of 20 Q&A pairs

Frequently Asked Questions

What API provider does the local SEO business listings feature use to fetch Q&A data?

The feature integrates with the DataForSEO API, specifically utilizing the business.questionsAnswers endpoint. This provider offers structured access to Google Business Profile questions and answers without requiring direct scraping of Google's interfaces.

How are location coordinates formatted for the Q&A search?

The system uses formatQuestionsAnswersCoordinate to convert latitude and longitude objects into the specific string format required by DataForSEO. This utility ensures geographic parameters align with the API's coordinate expectations before request transmission.

What authentication mechanism protects the DataForSEO API calls?

All calls are protected by withMcpProjectAuth, which validates the current project's billing context and permissions before creating an authenticated client via createDataforseoClient. This ensures only authorized projects with valid billing can consume API credits.

Can the number of results be customized when fetching questions?

Yes, the depth parameter controls result volume and defaults to 20 Q&A rows. Users can specify alternative values to retrieve larger or smaller datasets depending on their analysis requirements, though higher depths consume additional API quota.

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