# 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:

```http
Authorization: Bearer YOUR_API_KEY
```

***

## Endpoints

### Get Upstream Metrics

Track how often your business appears in AI assistant responses.

```http
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**:

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

**Response**:

```json
{
  "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.

```http
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**:

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

**Response**:

```json
{
  "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.

```http
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**:

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

**Response**:

```json
{
  "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.

```http
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**:

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

**Response**:

```json
{
  "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

```javascript
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

```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

```bash
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](https://amistan.gitbook.io/aidp-docs/for-developers/api-reference/business) - Manage business profiles
* [Search API](https://amistan.gitbook.io/aidp-docs/for-developers/api-reference/search) - Search businesses
* [Analytics Dashboard](https://amistan.gitbook.io/aidp-docs/for-business-owners/analytics) - Web interface
* [Upstream Metrics Guide](https://amistan.gitbook.io/aidp-docs/for-business-owners/analytics/upstream-metrics)
* [Intent Journeys Guide](https://amistan.gitbook.io/aidp-docs/for-business-owners/analytics/intent-journeys)
* [Attribution Guide](https://amistan.gitbook.io/aidp-docs/for-business-owners/analytics/attribution)

***

**API Version**: v1\
**Last Updated**: December 2025