get_domain_visitors
Retrieve website visitor analytics from specific domains using Clicky data, including visitor counts and page-level traffic details for any date range.
Instructions
Get visitors filtered by domain from Clicky analytics with optional segmentation data
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Domain name to filter by (e.g., "facebook.com", "google.com") | |
| end_date | Yes | End date in YYYY-MM-DD format | |
| limit | No | Optional limit for results (max 1000) | |
| segments | No | Optional array of segments to include (pages, visitors). Defaults to visitors only. "visitors" gets the total number of visitors from the domain. "pages" get the list of pages and its visited count from the domain. | |
| start_date | Yes | Start date in YYYY-MM-DD format |
Implementation Reference
- src/tools/get-domain-visitors.ts:43-74 (handler)The primary handler function that executes the tool logic: processes input arguments, creates DateRange, calls ClickyClient.getDomainVisitors, formats response as JSON or error.export async function handleGetDomainVisitors( args: { domain: string; start_date: string; end_date: string; segments?: string[]; limit?: number }, clickyClient: ClickyClient ) { try { const dateRange: DateRange = { startDate: args.start_date, endDate: args.end_date }; const data = await clickyClient.getDomainVisitors(args.domain, dateRange, args.segments, args.limit); return { content: [ { type: 'text', text: JSON.stringify(data, null, 2) } ] }; } catch (error) { return { content: [ { type: 'text', text: `Error fetching domain visitors: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } }
- Input schema defining parameters: domain (required), start_date/end_date (YYYY-MM-DD, required), optional segments (pages/visitors), limit (1-1000).inputSchema: { type: 'object', properties: { domain: { type: 'string', description: 'Domain name to filter by (e.g., "facebook.com", "google.com")' }, start_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', description: 'Start date in YYYY-MM-DD format' }, end_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', description: 'End date in YYYY-MM-DD format' }, segments: { type: 'array', items: { type: 'string', enum: ['pages', 'visitors'] }, description: 'Optional array of segments to include (pages, visitors). Defaults to visitors only. "visitors" gets the total number of visitors from the domain. "pages" get the list of pages and its visited count from the domain.' }, limit: { type: 'number', minimum: 1, maximum: 1000, description: 'Optional limit for results (max 1000)' } }, required: ['domain', 'start_date', 'end_date'] }
- src/index.ts:93-98 (registration)Tool is registered/returned in the ListToolsRequest handler's tools array.getTotalVisitorsTool, getDomainVisitorsTool, getTopPagesTool, getTrafficSourcesTool, getPageTrafficTool, ],
- src/index.ts:109-110 (registration)Tool dispatch/registration in the CallToolRequest switch statement, calling the handler.case 'get_domain_visitors': return await handleGetDomainVisitors(args as any, this.clickyClient);
- src/clicky-client.ts:60-80 (helper)Supporting ClickyClient method that performs the actual API request for domain visitors data via Clicky segmentation endpoint.async getDomainVisitors(domain: string, dateRange: DateRange, segments?: string[], limit?: number): Promise<any> { this.validateDateRange(dateRange); const params: any = { site_id: this.siteId, sitekey: this.siteKey, type: 'segmentation', domain: domain, segments: segments ? segments.join(',') : 'visitors', date: `${dateRange.startDate},${dateRange.endDate}`, output: 'json' }; if (limit) { params.limit = Math.min(limit, 1000); // API max is 1000 } const response = await this.client.get('', { params }); return response.data; }