search_single_term

Find People Also Ask questions for a single search term to support SEO research and content optimization.

Instructions

Search for PAA questions for a single term (convenience method)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`term`	Yes	Single search term
`language`	No	Language code	en
`region`	No	Region code	us
`latitude`	No	Latitude for geographic targeting
`longitude`	No	Longitude for geographic targeting
`depth`	No	Depth of question hierarchy

Implementation Reference

src/index.ts:227-231 (handler)
Handler for 'search_single_term' tool: validates arguments using validateSingleTermArgs, wraps the single term into a terms array, and delegates execution to the shared handleSearch method.
```
case 'search_single_term':
  const singleTermArgs = this.validateSingleTermArgs(args);
  const { term, ...otherArgs } = singleTermArgs;
  return await this.handleSearch({ terms: [term], ...otherArgs });
```

src/index.ts:176-210 (schema)

Input schema definition for the 'search_single_term' tool, specifying parameters like term (required), language, region, geo coordinates, and depth.

inputSchema: {
  type: 'object',
  properties: {
    term: {
      type: 'string',
      description: 'Single search term',
    },
    language: {
      type: 'string',
      description: 'Language code',
      default: 'en',
    },
    region: {
      type: 'string',
      description: 'Region code', 
      default: 'us',
    },
    latitude: {
      type: 'number',
      description: 'Latitude for geographic targeting',
    },
    longitude: {
      type: 'number',
      description: 'Longitude for geographic targeting',
    },
    depth: {
      type: 'integer',
      description: 'Depth of question hierarchy',
      default: 2,
      minimum: 1,
      maximum: 3,
    },
  },
  required: ['term'],
},

src/index.ts:173-211 (registration)

Registration of the 'search_single_term' tool in the ListTools response array, including name, description, and input schema.

{
  name: 'search_single_term',
  description: 'Search for PAA questions for a single term (convenience method)',
  inputSchema: {
    type: 'object',
    properties: {
      term: {
        type: 'string',
        description: 'Single search term',
      },
      language: {
        type: 'string',
        description: 'Language code',
        default: 'en',
      },
      region: {
        type: 'string',
        description: 'Region code', 
        default: 'us',
      },
      latitude: {
        type: 'number',
        description: 'Latitude for geographic targeting',
      },
      longitude: {
        type: 'number',
        description: 'Longitude for geographic targeting',
      },
      depth: {
        type: 'integer',
        description: 'Depth of question hierarchy',
        default: 2,
        minimum: 1,
        maximum: 3,
      },
    },
    required: ['term'],
  },
},

src/index.ts:267-287 (helper)

validateSingleTermArgs helper function: input validation and normalization specific to search_single_term tool arguments.

private validateSingleTermArgs(args: Record<string, unknown> | undefined): { term: string } & Partial<SearchRequestOptions> {
  if (!args || typeof args !== 'object') {
    throw new Error('Invalid arguments provided');
  }

  if (!args.term || typeof args.term !== 'string') {
    throw new Error('term parameter is required and must be a string');
  }

  return {
    term: args.term,
    language: typeof args.language === 'string' ? args.language : undefined,
    region: typeof args.region === 'string' ? args.region : undefined,
    latitude: typeof args.latitude === 'number' ? args.latitude : undefined,
    longitude: typeof args.longitude === 'number' ? args.longitude : undefined,
    depth: typeof args.depth === 'number' ? args.depth : undefined,
    fresh: typeof args.fresh === 'boolean' ? args.fresh : undefined,
    async: typeof args.async === 'boolean' ? args.async : undefined,
    notifyWebhooks: typeof args.notifyWebhooks === 'boolean' ? args.notifyWebhooks : undefined,
  };
}

src/index.ts:289-341 (helper)

handleSearch core helper: executes the API request to AlsoAsked /search endpoint, processes and formats the response into structured JSON output. Shared with search_people_also_ask tool.

private async handleSearch(options: SearchRequestOptions) {
  const searchData: SearchRequestOptions = {
    terms: options.terms,
    language: options.language || 'en',
    region: options.region || 'us', 
    latitude: options.latitude,
    longitude: options.longitude,
    depth: options.depth || 2,
    fresh: options.fresh || false,
    async: options.async || false,
    notifyWebhooks: options.notifyWebhooks || false,
  };

  // Remove undefined values to avoid sending them to the API
  Object.keys(searchData).forEach(key => {
    if (searchData[key as keyof SearchRequestOptions] === undefined) {
      delete searchData[key as keyof SearchRequestOptions];
    }
  });

  const response: SearchResponse = await this.makeApiRequest('/search', {
    method: 'POST',
    body: JSON.stringify(searchData),
  });

  if (response.status !== 'success') {
    throw new Error(`Search failed: ${response.message || 'Unknown error'}`);
  }

  // Format results for better readability
  const formattedResults = response.queries.map(query => ({
    searchTerm: query.term,
    totalQuestions: this.countTotalQuestions(query.results),
    questions: this.formatQuestionHierarchy(query.results),
  }));

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          status: response.status,
          searchId: response.id,
          results: formattedResults,
          summary: {
            totalSearchTerms: response.queries.length,
            totalQuestions: formattedResults.reduce((sum, result) => sum + result.totalQuestions, 0),
          }
        }, null, 2),
      },
    ],
  };
}

AlsoAsked MCP Server