get_traffic_sources
Retrieve traffic sources breakdown from Clicky analytics for any date range, with optional filtering by specific page URL to analyze visitor origins and referral patterns.
Instructions
Get traffic sources breakdown from Clicky analytics. Optionally filter by specific page URL.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | End date in YYYY-MM-DD format | |
| page_url | No | Optional: Full URL or path of the page to get traffic sources for (e.g., https://example.com/path or /path) | |
| start_date | Yes | Start date in YYYY-MM-DD format |
Implementation Reference
- src/tools/get-traffic-sources.ts:29-73 (handler)The handler function that executes the tool logic: parses args, calls ClickyClient.getTrafficSources, transforms data to JSON, handles errors.export async function handleGetTrafficSources( args: { start_date: string; end_date: string; page_url?: string }, clickyClient: ClickyClient ) { try { const dateRange: DateRange = { startDate: args.start_date, endDate: args.end_date }; const data = await clickyClient.getTrafficSources(dateRange, args.page_url); // Transform the response to be LLM-friendly const cleanedData = data.map((typeData: any) => ({ type: typeData.type, dates: typeData.dates.map((dateData: any) => ({ date: dateData.date, traffic_sources: dateData.items.map((item: any) => ({ source: item.title, visitors: parseInt(item.value), percentage: parseFloat(item.value_percent || '0') })) })) })); return { content: [ { type: 'text', text: JSON.stringify(cleanedData, null, 2) } ] }; } catch (error) { return { content: [ { type: 'text', text: `Error fetching traffic sources: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } }
- Tool definition including name, description, and input schema for start_date, end_date (required), page_url (optional).export const getTrafficSourcesTool: Tool = { name: 'get_traffic_sources', description: 'Get traffic sources breakdown from Clicky analytics. Optionally filter by specific page URL.', inputSchema: { type: 'object', properties: { 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' }, page_url: { type: 'string', description: 'Optional: Full URL or path of the page to get traffic sources for (e.g., https://example.com/path or /path)' } }, required: ['start_date', 'end_date'] } };
- src/index.ts:91-99 (registration)Registers the tool in the listTools handler by including getTrafficSourcesTool in the tools array.this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ getTotalVisitorsTool, getDomainVisitorsTool, getTopPagesTool, getTrafficSourcesTool, getPageTrafficTool, ], }));
- src/index.ts:115-116 (registration)Registers the handler dispatch in the switch statement for CallToolRequest.case 'get_traffic_sources': return await handleGetTrafficSources(args as any, this.clickyClient);
- src/clicky-client.ts:101-134 (helper)ClickyClient method that makes the API call to fetch traffic sources data, handling page-specific segmentation.async getTrafficSources(dateRange: DateRange, pageUrl?: string): Promise<any> { this.validateDateRange(dateRange); let params: any = { site_id: this.siteId, sitekey: this.siteKey, date: `${dateRange.startDate},${dateRange.endDate}`, output: 'json' }; if (pageUrl) { // Extract path from URL and encode it let path: string; try { const urlObj = new URL(pageUrl); path = urlObj.pathname; } catch (error) { // If URL parsing fails, assume it's already a path path = pageUrl.startsWith('/') ? pageUrl : '/' + pageUrl; } // Use segmentation API for page-specific traffic sources params.type = 'segmentation'; params.href = path; // Axios will handle the URL encoding automatically params.segments = 'traffic-sources'; } else { // Use general traffic sources API params.type = 'traffic-sources'; } const response = await this.client.get('', { params }); return response.data; }