# Get parking analytics

`GET https://api.parklio.com/v2/parking-analytics`

Returns parking analytics data based on the provided filters.

---

### Metrics (`metric` filter)

| Metric | Description |
|--------|-------------|
| `average_duration` | The average time (in minutes) a vehicle spends parked |
| `average_duration_percentage` | The average duration as a percentage of the maximum allowed parking time |
| `total_duration` | The total cumulative time (in minutes) all vehicles spent parked |
| `turnover_rate` | The number of different vehicles that occupied a spot over a given period |
| `peak_occupancy_hour` | The hour of the day (0–23) with the highest occupancy |

---

### Scopes (`scope` filter)

| Scope | Description | ID filter |
|-------|-------------|-----------|
| `lot` | Aggregates data per parking lot | `lot_ids` |
| `zone` | Aggregates data per zone within a lot | `zone_ids` |
| `place` | Aggregates data per individual parking place | `parking_place_ids` |
| *(none)* | No scope provided — returns a single aggregated result across all matched entities | — |

---

### Intervals (`interval` filter)

| Interval | Description | Response shape |
|----------|-------------|----------------|
| *(none)* | No interval — returns a single cumulative value | `number` |
| `hour` | Breaks data down by hour of the day | `number[]` with 24 values (index 0 = midnight, 23 = 11PM) |
| `day` | Breaks data down by day of the week | `number[]` with 7 values (index 0 = Sunday, 6 = Saturday) |
| `month` | Breaks data down by month of the year | `number[]` with 12 values (index 0 = January, 11 = December) |

---

> **Note:** `peak_occupancy_hour` does not support intervals — it always returns a single `number | null` value regardless of the `interval` filter.

**Auth:** `Authorization: Bearer <token>`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | string[] | yes | Filter as `field:rule:value`, for example `lot_id:eq:7`. Repeat `filter` to combine filters; all must match. See [Filtering](/api/conventions#filtering). |

## Responses

### 200 — Returns analytics data based on the provided filters.

```json
[
  null
]
```

### 403 — User is trying to filter where end time is before start time.

```json
{
  "success": false,
  "errors": [
    {
      "code": 306,
      "message": "End time is before start time."
    }
  ]
}
```

### 422 — Some of the provided request parameters are missing or are invalid. User should add/change them according to response message.

```json
{
  "success": false,
  "errors": [
    {
      "code": 23,
      "message": "Validation error",
      "field": "field"
    }
  ]
}
```