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.

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.

Parameter	Supported Intervals	Default
start_hour_filter	All	Location's configured operating hours
end_hour_filter	All	Location's configured operating hours
days_filter	All	Location's configured operating days

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.

Parameter	Type	Valid Values	Description
start_hour_filter	integer	0-23	Only include data at or after this hour of the day
end_hour_filter	integer	0-23	Only include data up to and including this hour of the day

# 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&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.

Code	Day
1	Sunday
2	Monday
3	Tuesday
4	Wednesday
5	Thursday
6	Friday
7	Saturday

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.

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

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

{
    "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:

Endpoint	Intervals
GET /locations/{id}/occupancy	daily, hourly, weekly, monthly, 60min, 30min, 15min
GET /locations/{id}/traffic	daily, weekly, monthly, 60min
GET /locations/{id}/dwell_time	daily, weekly, monthly
GET /locations/{id}/availability	daily, hourly, weekly, monthly, 60min