> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard Analytics API

> Retrieve comprehensive dashboard statistics and performance metrics

## Overview

The Dashboard Analytics API provides aggregated statistics and performance metrics for your dealership operations. Get real-time insights into sales, inventory, and customer metrics with flexible time period filtering.

## Endpoints

### Get Dashboard Statistics

<ParamField path="GET" type="endpoint">
  /analytics/dashboard/stats
</ParamField>

Retrieve comprehensive dashboard statistics including KPI values and trends.

**Query Parameters:**

<ParamField query="period" type="enum">
  Time period for statistics calculation. Options:

  * `last7days` - Last 7 days
  * `last30days` - Last 30 days (default)
  * `last90days` - Last 90 days
  * `thisWeek` - Current week (Monday-Sunday)
  * `lastWeek` - Previous week
  * `thisMonth` - Current calendar month
  * `lastMonth` - Previous calendar month
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "avgDaysToSell": {
      "current": 28.5,
      "previous": 32.4,
      "change": -3.9,
      "changePercentage": -12.0,
      "trend": "down",
      "unit": "days"
    },
    "avgSellingPrice": {
      "current": 185000,
      "previous": 178500,
      "change": 6500,
      "changePercentage": 3.6,
      "trend": "up",
      "unit": "MAD"
    },
    "grossProfitMargin": {
      "current": 18.5,
      "previous": 17.2,
      "change": 1.3,
      "changePercentage": 7.6,
      "trend": "up",
      "unit": "%"
    },
    "avgAgeOfInventory": {
      "current": 45.2,
      "previous": 48.1,
      "change": -2.9,
      "changePercentage": -6.0,
      "trend": "down",
      "unit": "days"
    },
    "inventoryTurnoverRatio": {
      "current": 8.1,
      "previous": 7.5,
      "change": 0.6,
      "changePercentage": 8.0,
      "trend": "up",
      "unit": "times/year"
    },
    "customerSatisfactionScore": {
      "current": 4.6,
      "previous": 4.5,
      "change": 0.1,
      "changePercentage": 2.2,
      "trend": "up",
      "unit": "out of 5"
    },
    "customerRetentionRate": {
      "current": 68.5,
      "previous": 65.2,
      "change": 3.3,
      "changePercentage": 5.1,
      "trend": "up",
      "unit": "%"
    },
    "totalRepairCost": {
      "current": 125400,
      "previous": 118900,
      "change": 6500,
      "changePercentage": 5.5,
      "trend": "up",
      "unit": "MAD"
    }
  },
  "meta": {
    "period": "last30days",
    "startDate": "2023-12-18",
    "endDate": "2024-01-17",
    "comparisonStartDate": "2023-11-18",
    "comparisonEndDate": "2023-12-17",
    "calculatedAt": "2024-01-17T10:30:00Z"
  }
}
```

**Stat Object Structure:**

Each statistic includes:

<ResponseField name="current" type="number">
  Current period value
</ResponseField>

<ResponseField name="previous" type="number">
  Previous period value for comparison
</ResponseField>

<ResponseField name="change" type="number">
  Absolute change between periods
</ResponseField>

<ResponseField name="changePercentage" type="number">
  Percentage change between periods
</ResponseField>

<ResponseField name="trend" type="enum">
  Trend direction: `up`, `down`, `stable`
</ResponseField>

<ResponseField name="unit" type="string">
  Unit of measurement (days, MAD, %, etc.)
</ResponseField>

***

### Get Inventory Turnover Chart Data

<ParamField path="GET" type="endpoint">
  /analytics/inventory-turnover
</ParamField>

Retrieve time-series data for inventory turnover visualization.

**Query Parameters:**

<ParamField query="period" type="enum">
  Time period for chart data (same options as dashboard stats)
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "day": "Monday",
      "date": "2024-01-01",
      "value": 7.8
    },
    {
      "day": "Tuesday",
      "date": "2024-01-02",
      "value": 8.1
    },
    {
      "day": "Wednesday",
      "date": "2024-01-03",
      "value": 8.3
    }
  ],
  "meta": {
    "period": "last7days",
    "dataPoints": 7,
    "average": 8.0,
    "min": 7.5,
    "max": 8.5
  }
}
```

***

## Metrics Explained

### Average Days to Sell

**What it measures:** The average number of days from when a vehicle is listed until it's sold.

**Formula:** `Total Days in Inventory / Number of Vehicles Sold`

**Good trend:** ⬇️ Lower is better - indicates faster sales

**Industry benchmark:** 30-45 days

***

### Average Selling Price

**What it measures:** The mean sale price of vehicles sold during the period.

**Formula:** `Total Revenue / Number of Vehicles Sold`

**Good trend:** ⬆️ Higher indicates better pricing or premium inventory

**Use case:** Track pricing strategy effectiveness

***

### Gross Profit Margin

**What it measures:** The percentage of revenue remaining after subtracting the cost of goods sold.

**Formula:** `((Revenue - COGS) / Revenue) × 100`

**Good trend:** ⬆️ Higher margins indicate better profitability

**Industry benchmark:** 15-20%

***

### Average Age of Inventory

**What it measures:** The average number of days vehicles have been in inventory.

**Formula:** `Sum of (Days Since Added) / Total Vehicles in Inventory`

**Good trend:** ⬇️ Lower indicates fresher inventory

**Alert threshold:** > 60 days (aging inventory)

***

### Inventory Turnover Ratio

**What it measures:** How many times inventory is sold and replaced over a period.

**Formula:** `Cost of Goods Sold / Average Inventory Value`

**Good trend:** ⬆️ Higher turnover means more efficient operations

**Industry benchmark:** 6-12 times per year

***

### Customer Satisfaction Score

**What it measures:** Average customer rating from feedback and reviews.

**Scale:** 1-5 stars

**Good trend:** ⬆️ Higher scores indicate better customer experience

**Target:** 4.5+

***

### Customer Retention Rate

**What it measures:** Percentage of customers who return for repeat business.

**Formula:** `(Repeat Customers / Total Customers) × 100`

**Good trend:** ⬆️ Higher retention reduces acquisition costs

**Industry benchmark:** 60-70%

***

### Total Repair Cost

**What it measures:** Total amount spent on vehicle repairs and refurbishment.

**Good trend:** ⬇️ Lower costs improve margins (but don't compromise quality)

**Use case:** Budget planning and cost control

***

## Time Period Comparisons

The API automatically compares each metric against the previous equivalent period:

| Current Period | Comparison Period |
| -------------- | ----------------- |
| last7days      | Previous 7 days   |
| last30days     | Previous 30 days  |
| last90days     | Previous 90 days  |
| thisWeek       | Last week         |
| lastWeek       | Week before last  |
| thisMonth      | Last month        |
| lastMonth      | Month before last |

## Caching

Dashboard statistics are cached for **5 minutes** to optimize performance. Subsequent requests within this window will return cached data.

To force a refresh, wait for the cache to expire or use cache-busting techniques.

## Use Cases

### Example 1: Weekly Performance Review

```bash theme={null}
# Get this week's stats
curl -X GET "https://api.steerai.autos/v1/analytics/dashboard/stats?period=thisWeek" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example 2: Monthly Business Review

```bash theme={null}
# Get last month's complete statistics
curl -X GET "https://api.steerai.autos/v1/analytics/dashboard/stats?period=lastMonth" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example 3: Quarterly Analysis

```bash theme={null}
# Get last 90 days for quarterly review
curl -X GET "https://api.steerai.autos/v1/analytics/dashboard/stats?period=last90days" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example 4: Visualize Inventory Trends

```bash theme={null}
# Get inventory turnover chart data
curl -X GET "https://api.steerai.autos/v1/analytics/inventory-turnover?period=last30days" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Integration Patterns

### Real-time Dashboard

```javascript theme={null}
// Fetch and display dashboard stats
async function updateDashboard() {
  const response = await fetch(
    'https://api.steerai.autos/v1/analytics/dashboard/stats?period=last30days',
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );

  const { data } = await response.json();

  // Display metrics
  displayMetric('avg-days-to-sell', data.avgDaysToSell);
  displayMetric('profit-margin', data.grossProfitMargin);
  // ... more metrics
}

// Refresh every 5 minutes (respects cache)
setInterval(updateDashboard, 300000);
```

### Trend Alerts

```javascript theme={null}
// Monitor for significant changes
function checkAlerts(data) {
  const alerts = [];

  // Alert if days to sell increased by more than 20%
  if (data.avgDaysToSell.changePercentage > 20) {
    alerts.push({
      type: 'warning',
      metric: 'Average Days to Sell',
      message: `Sales velocity decreased by ${data.avgDaysToSell.changePercentage}%`
    });
  }

  // Alert if inventory aging
  if (data.avgAgeOfInventory.current > 60) {
    alerts.push({
      type: 'danger',
      metric: 'Inventory Age',
      message: 'Inventory aging beyond 60 days threshold'
    });
  }

  return alerts;
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Choose appropriate time periods">
    Use shorter periods (7 days) for operational metrics, longer periods (90 days) for strategic decisions.
  </Accordion>

  <Accordion title="Monitor trends, not just values">
    Focus on the `trend` and `changePercentage` fields to identify improving or declining performance.
  </Accordion>

  <Accordion title="Set up automated alerts">
    Configure alerts when metrics exceed thresholds (e.g., days to sell > 45).
  </Accordion>

  <Accordion title="Respect cache timing">
    The 5-minute cache improves performance. Don't poll more frequently than necessary.
  </Accordion>

  <Accordion title="Compare like periods">
    Ensure you're comparing equivalent time periods (e.g., same day of week, same month).
  </Accordion>
</AccordionGroup>

## Error Codes

| Code                      | Status | Description                              |
| ------------------------- | ------ | ---------------------------------------- |
| `INVALID_PERIOD`          | 400    | Invalid time period specified            |
| `INSUFFICIENT_DATA`       | 400    | Not enough data for the requested period |
| `ANALYTICS_SERVICE_ERROR` | 500    | Error calculating statistics             |

## Related Resources

<CardGroup cols={2}>
  <Card title="KPI Dashboard API" icon="gauge-high" href="/api-reference/analytics/kpi-dashboard">
    Manage individual KPI configurations
  </Card>

  <Card title="Dashboard KPIs Guide" icon="book" href="/guides/dashboard-kpis">
    Learn to optimize your dashboard
  </Card>

  <Card title="Data-Driven Decisions" icon="chart-line" href="/guides/data-driven-decisions">
    Use analytics for business strategy
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Source data for analytics
  </Card>
</CardGroup>