# Filters

The Occuspace API supports optional filters on all metric endpoints that allow you to narrow data to specific hours of the day and days of the week. Filters are independent of each other and can be used in any combination.

### Overview

By default, metric endpoints return data based on each location's configured operating hours and days. Filters allow you to override these defaults and focus on a specific time window that is meaningful for your analysis — for example, only business hours on weekdays, or just weekend afternoons.

{% hint style="info" %}
**Filters are reflected in the response.** Every metric response includes `hour_range` and `days_of_week` fields that echo back the filters applied to the request. If no filters were provided, these fields reflect the location's default operating hours and days — making it easy to verify exactly what data window was used.
{% endhint %}

<table><thead><tr><th width="179.95703125">Parameter</th><th width="196.1875">Supported Intervals</th><th>Default</th></tr></thead><tbody><tr><td><code>start_hour_filter</code></td><td>All</td><td>Location's configured operating hours</td></tr><tr><td><code>end_hour_filter</code></td><td>All</td><td>Location's configured operating hours</td></tr><tr><td><code>days_filter</code></td><td>All</td><td>Location's configured operating days</td></tr></tbody></table>

### Hour Filter

The `start_hour_filter` and `end_hour_filter` parameters let you restrict data to a specific range of hours within each day. Hours are expressed as integers from 0 to 23 using a 24-hour clock. The filters can be used independently — you can provide just `start_hour_filter`, just `end_hour_filter`, or both together.

<table><thead><tr><th width="175.09765625">Parameter</th><th width="96.234375">Type</th><th width="133.97265625">Valid Values</th><th>Description</th></tr></thead><tbody><tr><td><code>start_hour_filter</code></td><td>integer</td><td>0-23</td><td>Only include data at or after this hour of the day</td></tr><tr><td><code>end_hour_filter</code></td><td>integer</td><td>0-23</td><td>Only include data up to and including this hour of the day</td></tr></tbody></table>

```bash
# Restrict data to business hours only (9am to 5pm)
curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&start_hour_filter=9&end_hour_filter=17" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Restrict data to morning hours only (no end_hour_filter needed)
curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&start_hour_filter=6&end_hour_filter=12" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Day Filter

The `days_filter` parameter lets you restrict data to specific days of the week. It is provided as a string of day code digits with no separator, where each digit represents a day of the week. Days can be provided in any order.

<table><thead><tr><th width="250.91015625">Code</th><th>Day</th></tr></thead><tbody><tr><td><code>1</code></td><td>Sunday</td></tr><tr><td><code>2</code></td><td>Monday</td></tr><tr><td><code>3</code></td><td>Tuesday</td></tr><tr><td><code>4</code></td><td>Wednesday</td></tr><tr><td><code>5</code></td><td>Thursday</td></tr><tr><td><code>6</code></td><td>Friday</td></tr><tr><td><code>7</code></td><td>Saturday</td></tr></tbody></table>

For example, to filter to weekdays only (Monday through Friday), pass `days_filter=23456`. To filter to weekends only (Saturday and Sunday), pass `days_filter=17`.

```bash
# Weekdays only (Monday through Friday)
curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&days_filter=23456" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Weekends only (Saturday and Sunday)
curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&days_filter=17" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Mid-week only (Tuesday, Wednesday, Thursday)
curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&days_filter=345" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Combining Filters

All three filters can be combined freely in a single request. For example, to analyze occupancy during business hours on weekdays only, combine `start_hour_filter`, `end_hour_filter`, and `days_filter` in the same request:

```bash
# Business hours (9am-5pm) on weekdays only (Monday through Friday)
curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&start_hour_filter=9&end_hour_filter=17&days_filter=23456" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

To confirm which filters were applied, check the `hour_range` and `days_of_week` fields in the response. These always reflect the exact time window used to calculate the returned data:

```json
{
    "location_id": 1559,
    "name": "Austin Office",
    "capacity": 10897,
    "metric": "occupancy",
    "interval": "daily",
    "time_range": {
        "start": "2025-12-01T00:00:00Z",
        "end": "2025-12-31T23:59:59Z"
    },
    "days_of_week": [2, 3, 4, 5, 6],
    "hour_range": {
        "start": 9,
        "end": 17
    },
    "data": [...],
    "pagination": {
        "has_more": false,
        "prev_cursor": null,
        "next_cursor": null
    }
}
```

### Supported Endpoints

Filters are supported on all four metric endpoints. Note that each endpoint supports a different set of intervals, so the intervals on which filters are valid vary accordingly:

<table><thead><tr><th width="302.91796875">Endpoint</th><th>Intervals</th></tr></thead><tbody><tr><td><code>GET /locations/{id}/occupancy</code></td><td>daily, hourly, weekly, monthly, 60min, 30min, 15min</td></tr><tr><td><code>GET /locations/{id}/traffic</code></td><td>daily, weekly, monthly, 60min</td></tr><tr><td><code>GET /locations/{id}/dwell_time</code></td><td>daily, weekly, monthly</td></tr><tr><td><code>GET /locations/{id}/availability</code></td><td>daily, hourly, weekly, monthly, 60min, 30min, 15min</td></tr></tbody></table>