Analytics Integration

Complete examples for displaying and analyzing business performance data.

Upstream Metrics

Basic Implementation (TypeScript)

import { AIDPClient } from '@aidp/sdk';

const client = new AIDPClient({
  apiKey: process.env.AIDP_API_KEY,
});

async function getUpstreamMetrics(businessId: string, period: string = 'last_30_days') {
  const metrics = await client.analytics.upstream({
    businessId,
    period,
  });

  return {
    impressions: metrics.data.totalImpressions,
    citations: metrics.data.totalCitations,
    citationRate: metrics.data.citationRate,
    platformBreakdown: metrics.data.platformBreakdown,
    trend: metrics.data.trend,
  };
}

// Usage
const metrics = await getUpstreamMetrics('biz_abc123');
console.log(`Impressions: ${metrics.impressions}`);
console.log(`Citation Rate: ${metrics.citationRate}%`);
console.log(`Platforms:`, metrics.platformBreakdown);

Python Implementation

from aidp import AIDPClient
import os

client = AIDPClient(api_key=os.environ['AIDP_API_KEY'])

def get_upstream_metrics(business_id: str, period: str = 'last_30_days'):
    metrics = client.analytics.upstream(
        business_id=business_id,
        period=period
    )

    return {
        'impressions': metrics.data.total_impressions,
        'citations': metrics.data.total_citations,
        'citation_rate': metrics.data.citation_rate,
        'platform_breakdown': metrics.data.platform_breakdown,
        'trend': metrics.data.trend
    }

# Usage
metrics = get_upstream_metrics('biz_abc123')
print(f"Impressions: {metrics['impressions']}")
print(f"Citation Rate: {metrics['citation_rate']}%")

---

Analytics Dashboard (React)

Complete Dashboard Component

import { useState, useEffect } from 'react';
import { AIDPClient } from '@aidp/sdk';
import { Line, Bar, Pie } from 'react-chartjs-2';

const client = new AIDPClient({ apiKey: process.env.NEXT_PUBLIC_AIDP_API_KEY });

export function AnalyticsDashboard({ businessId }: { businessId: string }) {
  const [metrics, setMetrics] = useState(null);
  const [loading, setLoading] = useState(true);
  const [period, setPeriod] = useState('last_30_days');

  useEffect(() => {
    loadMetrics();
  }, [businessId, period]);

  const loadMetrics = async () => {
    setLoading(true);
    try {
      const [upstream, journeys, attribution] = await Promise.all([
        client.analytics.upstream({ businessId, period }),
        client.analytics.intentJourneys({ businessId, period }),
        client.analytics.attribution({ businessId, period })
      ]);

      setMetrics({ upstream, journeys, attribution });
    } catch (error) {
      console.error('Failed to load metrics:', error);
    } finally {
      setLoading(false);
    }
  };

  if (loading) return <div>Loading analytics...</div>;
  if (!metrics) return <div>No data available</div>;

  return (
    <div className="analytics-dashboard">
      <div className="period-selector">
        <select value={period} onChange={(e) => setPeriod(e.target.value)}>
          <option value="last_7_days">Last 7 Days</option>
          <option value="last_30_days">Last 30 Days</option>
          <option value="last_90_days">Last 90 Days</option>
          <option value="last_year">Last Year</option>
        </select>
      </div>

      <div className="metrics-grid">
        <MetricCard
          title="Total Impressions"
          value={metrics.upstream.data.totalImpressions}
          trend={metrics.upstream.data.trend}
        />
        <MetricCard
          title="Citations"
          value={metrics.upstream.data.totalCitations}
          trend={metrics.upstream.data.trend}
        />
        <MetricCard
          title="Citation Rate"
          value={`${metrics.upstream.data.citationRate}%`}
          trend={metrics.upstream.data.trend}
        />
        <MetricCard
          title="AI Visibility Score"
          value={metrics.upstream.data.aiVisibilityScore}
          trend={metrics.upstream.data.trend}
        />
      </div>

      <div className="charts-grid">
        <div className="chart">
          <h3>Impressions Over Time</h3>
          <Line data={getImpressionsChartData(metrics.upstream.data)} />
        </div>

        <div className="chart">
          <h3>Platform Breakdown</h3>
          <Pie data={getPlatformChartData(metrics.upstream.data)} />
        </div>

        <div className="chart">
          <h3>Intent Journeys</h3>
          <Bar data={getJourneysChartData(metrics.journeys.data)} />
        </div>

        <div className="chart">
          <h3>Attribution</h3>
          <Bar data={getAttributionChartData(metrics.attribution.data)} />
        </div>
      </div>
    </div>
  );
}

function MetricCard({ title, value, trend }) {
  const trendColor = trend > 0 ? 'green' : trend < 0 ? 'red' : 'gray';
  const trendIcon = trend > 0 ? '↑' : trend < 0 ? '↓' : '→';

  return (
    <div className="metric-card">
      <h4>{title}</h4>
      <div className="value">{value}</div>
      <div className="trend" style={{ color: trendColor }}>
        {trendIcon} {Math.abs(trend)}%
      </div>
    </div>
  );
}

function getImpressionsChartData(data) {
  return {
    labels: data.timeline.map(t => t.date),
    datasets: [{
      label: 'Impressions',
      data: data.timeline.map(t => t.impressions),
      borderColor: 'rgb(75, 192, 192)',
      tension: 0.1
    }]
  };
}

function getPlatformChartData(data) {
  return {
    labels: Object.keys(data.platformBreakdown),
    datasets: [{
      data: Object.values(data.platformBreakdown),
      backgroundColor: [
        'rgba(255, 99, 132, 0.8)',
        'rgba(54, 162, 235, 0.8)',
        'rgba(255, 206, 86, 0.8)',
      ]
    }]
  };
}

function getJourneysChartData(data) {
  return {
    labels: ['Awareness', 'Consideration', 'Decision'],
    datasets: [{
      label: 'Intent Journeys',
      data: [
        data.awarenessStage,
        data.considerationStage,
        data.decisionStage
      ],
      backgroundColor: 'rgba(75, 192, 192, 0.8)'
    }]
  };
}

function getAttributionChartData(data) {
  return {
    labels: data.touchpoints.map(t => t.platform),
    datasets: [{
      label: 'Conversions',
      data: data.touchpoints.map(t => t.conversions),
      backgroundColor: 'rgba(153, 102, 255, 0.8)'
    }]
  };
}

---

Intent Journeys

Visualize Customer Journey

async function getIntentJourneys(businessId: string) {
  const journeys = await client.analytics.intentJourneys({
    businessId,
    period: 'last_30_days',
  });

  return {
    totalJourneys: journeys.data.total,
    stages: {
      awareness: journeys.data.awarenessStage,
      consideration: journeys.data.considerationStage,
      decision: journeys.data.decisionStage,
    },
    avgTurnsToConversion: journeys.data.avgTurnsToConversion,
    topQueries: journeys.data.topQueries,
  };
}

// Usage
const journeys = await getIntentJourneys('biz_abc123');
console.log(`Total Journeys: ${journeys.totalJourneys}`);
console.log(`Avg Turns to Conversion: ${journeys.avgTurnsToConversion}`);
console.log(`Top Queries:`, journeys.topQueries);

---

Competitive Benchmarking

Compare with Competitors

async function getBenchmarks(businessId: string) {
  const benchmarks = await client.analytics.benchmarks({
    businessId,
    category: 'restaurants',
    location: { city: 'Portland', state: 'OR' },
  });

  return {
    yourScore: benchmarks.data.yourScore,
    categoryAverage: benchmarks.data.categoryAverage,
    topPerformer: benchmarks.data.topPerformer,
    ranking: benchmarks.data.ranking,
    totalBusinesses: benchmarks.data.totalBusinesses,
  };
}

// Usage
const benchmarks = await getBenchmarks('biz_abc123');
console.log(`Your Score: ${benchmarks.yourScore}`);
console.log(`Category Average: ${benchmarks.categoryAverage}`);
console.log(`Ranking: ${benchmarks.ranking} of ${benchmarks.totalBusinesses}`);

---

Attribution Tracking

Multi-Touch Attribution

async function getAttribution(businessId: string, model: string = 'multi_touch') {
  const attribution = await client.analytics.attribution({
    businessId,
    model, // 'first_touch', 'last_touch', 'multi_touch', 'time_decay'
    period: 'last_30_days',
  });

  return {
    totalConversions: attribution.data.totalConversions,
    touchpoints: attribution.data.touchpoints,
    avgTouchpoints: attribution.data.avgTouchpoints,
    conversionRate: attribution.data.conversionRate,
  };
}

// Usage
const attribution = await getAttribution('biz_abc123', 'multi_touch');
console.log(`Total Conversions: ${attribution.totalConversions}`);
console.log(`Avg Touchpoints: ${attribution.avgTouchpoints}`);
console.log(`Conversion Rate: ${attribution.conversionRate}%`);

---

Real-Time Updates

WebSocket Integration

import { AIDPClient } from '@aidp/sdk';

const client = new AIDPClient({ apiKey: process.env.AIDP_API_KEY });

// Subscribe to real-time analytics updates
const subscription = client.analytics.subscribe({
  businessId: 'biz_abc123',
  events: ['impression', 'citation', 'journey_stage'],
  onUpdate: (event) => {
    console.log('New event:', event);
    updateDashboard(event);
  },
  onError: (error) => {
    console.error('Subscription error:', error);
  },
});

// Unsubscribe when done
subscription.unsubscribe();

---

Export Analytics

Export to CSV

async function exportAnalytics(businessId: string, format: 'csv' | 'json' | 'pdf') {
  const data = await client.analytics.export({
    businessId,
    period: 'last_30_days',
    format,
    metrics: ['upstream', 'journeys', 'attribution'],
  });

  // Download file
  const blob = new Blob([data], { type: `text/${format}` });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = `analytics-${businessId}-${Date.now()}.${format}`;
  a.click();
}

// Usage
await exportAnalytics('biz_abc123', 'csv');

---

Custom Reports

Generate Custom Report

async function generateCustomReport(businessId: string, config: ReportConfig) {
  const report = await client.analytics.customReport({
    businessId,
    startDate: config.startDate,
    endDate: config.endDate,
    metrics: config.metrics,
    groupBy: config.groupBy, // 'day', 'week', 'month'
    filters: config.filters,
  });

  return report.data;
}

interface ReportConfig {
  startDate: string;
  endDate: string;
  metrics: string[];
  groupBy: 'day' | 'week' | 'month';
  filters?: {
    platform?: string[];
    minImpressions?: number;
  };
}

// Usage
const report = await generateCustomReport('biz_abc123', {
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  metrics: ['impressions', 'citations', 'journeys'],
  groupBy: 'month',
  filters: {
    platform: ['claude', 'chatgpt'],
    minImpressions: 100,
  },
});

---

Previous: Search Examples ←