Analytics API

Track business performance and AI visibility metrics using the AIDP Analytics API.

Base URL

https://api.aidp.dev/v1

Authentication

All API requests require authentication via API key:

Authorization: Bearer YOUR_API_KEY

---

Endpoints

Get Upstream Metrics

Track how often your business appears in AI assistant responses.

GET /analytics/upstream-metrics

Query Parameters:

Parameter	Type	Required	Description
businessId	string	Yes	Business ID
startDate	string	Yes	Start date (ISO 8601)
endDate	string	Yes	End date (ISO 8601)
platform	string	No	Filter by AI platform
granularity	string	No	day, week, or month (default: day)

Example:

GET /analytics/upstream-metrics?businessId=biz_abc123&startDate=2025-01-01&endDate=2025-01-31&granularity=day

Response:

{
  "businessId": "biz_abc123",
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "metrics": {
    "impressions": 1247,
    "citations": 342,
    "comparisons": 89,
    "zeroClick": 156
  },
  "platforms": [
    {
      "name": "Claude",
      "impressions": 523,
      "citations": 145,
      "share": 0.42
    },
    {
      "name": "ChatGPT",
      "impressions": 412,
      "citations": 118,
      "share": 0.33
    },
    {
      "name": "Perplexity",
      "impressions": 312,
      "citations": 79,
      "share": 0.25
    }
  ],
  "timeSeries": [
    {
      "date": "2025-01-01",
      "impressions": 42,
      "citations": 12
    },
    {
      "date": "2025-01-02",
      "impressions": 38,
      "citations": 9
    }
  ]
}

Metrics Explained:

• Impressions: Times your business appeared in AI responses

• Citations: Times your business was specifically mentioned

• Comparisons: Times shown alongside competitors

• Zero-Click: Visibility without user clicking through

---

Get Intent Journeys

Track how customers discover your business through AI conversations.

GET /analytics/intent-journeys

Query Parameters:

Parameter	Type	Required	Description
businessId	string	Yes	Business ID
startDate	string	Yes	Start date (ISO 8601)
endDate	string	Yes	End date (ISO 8601)
stage	string	No	Filter by journey stage

Journey Stages:

• awareness - Initial discovery

• consideration - Comparing options

• intent - Showing purchase intent

• conversion - Taking action

Example:

GET /analytics/intent-journeys?businessId=biz_abc123&startDate=2025-01-01&endDate=2025-01-31

Response:

{
  "businessId": "biz_abc123",
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "journeys": {
    "total": 342,
    "byStage": {
      "awareness": 156,
      "consideration": 98,
      "intent": 64,
      "conversion": 24
    },
    "conversionRate": 0.07,
    "avgTouchpoints": 4.2,
    "avgDuration": 172800
  },
  "topQueries": [
    {
      "query": "coffee shop with outdoor seating",
      "count": 89,
      "conversionRate": 0.12
    },
    {
      "query": "best coffee in Portland",
      "count": 67,
      "conversionRate": 0.09
    }
  ]
}

---

Get Attribution Data

Understand which touchpoints drive conversions.

GET /analytics/attribution

Query Parameters:

Parameter	Type	Required	Description
businessId	string	Yes	Business ID
startDate	string	Yes	Start date (ISO 8601)
endDate	string	Yes	End date (ISO 8601)
model	string	No	Attribution model (default: multiTouch)

Attribution Models:

• firstTouch - Credit to first interaction

• lastTouch - Credit to last interaction

• linear - Equal credit to all touchpoints

• multiTouch - Weighted credit (default)

Example:

GET /analytics/attribution?businessId=biz_abc123&startDate=2025-01-01&endDate=2025-01-31&model=multiTouch

Response:

{
  "businessId": "biz_abc123",
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "model": "multiTouch",
  "conversions": 24,
  "touchpoints": [
    {
      "type": "impression",
      "platform": "Claude",
      "credit": 0.25,
      "conversions": 6
    },
    {
      "type": "citation",
      "platform": "ChatGPT",
      "credit": 0.35,
      "conversions": 8.4
    },
    {
      "type": "comparison",
      "platform": "Perplexity",
      "credit": 0.20,
      "conversions": 4.8
    },
    {
      "type": "website_visit",
      "platform": "direct",
      "credit": 0.20,
      "conversions": 4.8
    }
  ]
}

---

Get Competitive Benchmarks

Compare your performance against similar businesses.

GET /analytics/benchmarks

Query Parameters:

Parameter	Type	Required	Description
businessId	string	Yes	Business ID
startDate	string	Yes	Start date (ISO 8601)
endDate	string	Yes	End date (ISO 8601)
category	string	No	Compare within category
location	string	No	Compare within location

Example:

GET /analytics/benchmarks?businessId=biz_abc123&startDate=2025-01-01&endDate=2025-01-31&category=restaurants

Response:

{
  "businessId": "biz_abc123",
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "yourMetrics": {
    "impressions": 1247,
    "citations": 342,
    "conversionRate": 0.07
  },
  "benchmarks": {
    "category": "restaurants",
    "location": "Portland, OR",
    "sampleSize": 127,
    "percentiles": {
      "impressions": {
        "p25": 420,
        "p50": 890,
        "p75": 1580,
        "yourPercentile": 68
      },
      "citations": {
        "p25": 120,
        "p50": 280,
        "p75": 520,
        "yourPercentile": 72
      },
      "conversionRate": {
        "p25": 0.04,
        "p50": 0.06,
        "p75": 0.09,
        "yourPercentile": 65
      }
    }
  }
}

---

Response Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - No access to this business
404	Business Not Found
429	Rate Limit Exceeded
500	Internal Server Error

---

Rate Limiting

• Free Tier: 100 requests/day

• Pro Tier: 1,000 requests/day

• Enterprise: Custom limits

---

Examples

Node.js

const axios = require('axios');

const getUpstreamMetrics = async (businessId, startDate, endDate) => {
  const response = await axios.get(
    'https://api.aidp.dev/v1/analytics/upstream-metrics',
    {
      params: {
        businessId,
        startDate,
        endDate,
        granularity: 'day'
      },
      headers: {
        'Authorization': `Bearer ${process.env.AIDP_API_KEY}`
      }
    }
  );
  
  return response.data;
};

Python

import requests

def get_upstream_metrics(business_id, start_date, end_date):
    response = requests.get(
        'https://api.aidp.dev/v1/analytics/upstream-metrics',
        params={
            'businessId': business_id,
            'startDate': start_date,
            'endDate': end_date,
            'granularity': 'day'
        },
        headers={
            'Authorization': f'Bearer {os.environ["AIDP_API_KEY"]}'
        }
    )
    
    return response.json()

cURL

curl -X GET "https://api.aidp.dev/v1/analytics/upstream-metrics?businessId=biz_abc123&startDate=2025-01-01&endDate=2025-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

See Also

• Business API - Manage business profiles

• Search API - Search businesses

• Analytics Dashboard - Web interface

• Upstream Metrics Guide

• Intent Journeys Guide

• Attribution Guide

---

API Version: v1 Last Updated: December 2025