serp_locations
Retrieve a list of available locations for SERP data analysis by specifying search engine, country code, and location type to enhance local SEO and search insights.
Instructions
Utility tool for serp_organic_live_advanced to get list of availible locations.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| country_iso_code | Yes | ISO 3166-1 alpha-2 country code, for example: US, GB, MT | |
| location_name | No | Name of location or it`s part. | |
| location_type | No | Type of location. Possible variants: 'TV Region','Postal Code','Neighborhood','Governorate','National Park','Quarter','Canton','Airport','Okrug','Prefecture','City','Country','Province','Barrio','Sub-District','Congressional District','Municipality District','district','DMA Region','Union Territory','Territory','Colloquial Area','Autonomous Community','Borough','County','State','District','City Region','Commune','Region','Department','Division','Sub-Ward','Municipality','University' | |
| search_engine | No | search engine name, one of: google, yahoo, bing. |
Implementation Reference
- The async handle() method implements the core logic of the 'serp_locations' tool. It constructs a payload from input parameters and sends a POST request to the DataForSEO /v3/serp/{search_engine}/locations endpoint, then validates and formats the response.async handle(params:any): Promise<any> { try { const payload: Record<string, unknown> = { 'country_iso_code': params.country_iso_code, }; if (params.location_type) { payload['location_type'] = params.location_type; } if (params.location_name) { payload['location_name'] = params.location_name; } const response = await this.dataForSEOClient.makeRequest(`/v3/serp/${params.search_engine}/locations`, 'POST', [payload]); return this.validateAndFormatResponse(response); } catch (error) { return this.formatErrorResponse(error); } }
- The getParams() method defines the Zod schema for input validation of the 'serp_locations' tool parameters: search_engine, country_iso_code, location_type, and location_name.getParams(): z.ZodRawShape { return { search_engine: z.string().default('google').describe("search engine name, one of: google, yahoo, bing."), country_iso_code: z.string().describe("ISO 3166-1 alpha-2 country code, for example: US, GB, MT"), location_type: z.string().optional().describe("Type of location. Possible variants: 'TV Region','Postal Code','Neighborhood','Governorate','National Park','Quarter','Canton','Airport','Okrug','Prefecture','City','Country','Province','Barrio','Sub-District','Congressional District','Municipality District','district','DMA Region','Union Territory','Territory','Colloquial Area','Autonomous Community','Borough','County','State','District','City Region','Commune','Region','Department','Division','Sub-Ward','Municipality','University'"), location_name: z.string().optional().describe("Name of location or it`s part.") }; }
- src/core/modules/serp/serp-api.module.ts:14-35 (registration)The getTools() method in SerpApiModule instantiates SerpOrganicLocationsListTool and registers it in the tools record using its getName() 'serp_locations' as the key, providing description, params, and a wrapper around its handle() method.getTools(): Record<string, ToolDefinition> { const tools = [ new SerpOrganicLiveAdvancedTool(this.dataForSEOClient), new SerpOrganicLocationsListTool(this.dataForSEOClient), new SerpYoutubeLocationsListTool(this.dataForSEOClient), new SerpYoutubeOrganicLiveAdvancedTool(this.dataForSEOClient), new SerpYoutubeVideoInfoLiveAdvancedTool(this.dataForSEOClient), new SerpYoutubeVideoCommentsLiveAdvancedTool(this.dataForSEOClient), new SerpYoutubeVideoSubtitlesLiveAdvancedTool(this.dataForSEOClient), // Add more tools here ]; return tools.reduce((acc, tool) => ({ ...acc, [tool.getName()]: { description: tool.getDescription(), params: tool.getParams(), handler: (params: any) => tool.handle(params), }, }), {}); }
- src/core/utils/module-loader.ts:21-23 (registration)The ModuleLoaderService loads the SerpApiModule (which contains the serp_locations tool) if the SERP module is enabled, making the tool available.if (isModuleEnabled('SERP', enabledModules)) { modules.push(new SerpApiModule(dataForSEOClient)); }