Metrics | Occuspace Docs

Get Occupancy metrics for a location

get

Returns historical occupancy metrics for a specific location over a given date range and interval. Supports optional hour and day filters for all intervals.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

The ID of the location.

Example: 1560

Query parameters

start_datestring · dateRequired

The start date of the requested time range in YYYY-MM-DD format.

Example: 2025-12-01

end_datestring · dateRequired

The end date of the requested time range in YYYY-MM-DD format.

Example: 2025-12-03

intervalstring · enumOptional

The time interval to aggregate occupancy data by.

Default: dailyExample: dailyPossible values:

limitintegerOptional

Maximum number of data points to return per page. Defaults to 1000 if not specified.

Default: 1000Example: 3

cursorstringOptional

Cursor value from the previous response's pagination object used to fetch the next or previous page of results.

Example: eyJsb2NhdGlvbl9pZCI6MTU2OH0

start_hour_filterinteger · max: 23Optional

Filter data to only include readings at or after this hour of the day. Valid values are 0-24. Only supported for daily, weekly, and monthly intervals.

Example: 9

end_hour_filterinteger · max: 23Optional

Filter data to only include readings before or at this hour of the day. Valid values are 0-24. Only supported for daily, weekly, and monthly intervals.

Example: 17

days_filterstringOptional

Filter data to only include specific days of the week. Provided as a string of day codes with no separator where 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday. For example '23456' means Monday through Friday. Only supported for daily, weekly, and monthly intervals.

Example: 23456Pattern: ^[1-7]+$

Responses

200

Occupancy metrics for the location

application/json

location_idintegerRequired

The ID of the location.

Example: 1560

namestringRequired

The name of the location.

Example: Austin Office

capacityintegerRequired

The total capacity of the location.

Example: 1341

metricstringRequired

The metric type returned.

Example: occupancy

intervalstring · enumRequired

The time interval used to aggregate the data.

Example: dailyPossible values:

days_of_weekinteger[]Required

The days of the week included in the response data. Reflects the days_filter parameter if provided, otherwise includes all days. 1=Sunday through 7=Saturday.

Example: [2,3,4,5,6]

400

Bad request — one or more request parameters are invalid

application/json

404

Location not found or not accessible with the provided credentials

application/json

500

Internal server error

application/json

get

/locations/{id}/occupancy

GET /v2/locations/{id}/occupancy?start_date=2025-12-01&end_date=2025-12-03 HTTP/1.1
Host: api.occuspace.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "location_id": 1560,
  "name": "Austin Office",
  "capacity": 1341,
  "metric": "occupancy",
  "interval": "daily",
  "time_range": {
    "start": "2025-12-01T00:00:00Z",
    "end": "2025-12-07T23:59:59Z"
  },
  "days_of_week": [
    2,
    3,
    4,
    5,
    6
  ],
  "hour_range": {
    "start": 0,
    "end": 17
  },
  "data": [
    {
      "timestamp": "2025-12-01T00:00:00Z",
      "window_start": "2025-12-01T00:00:00Z",
      "window_end": "2025-12-01T23:59:59Z",
      "avg_occupancy": 372,
      "avg_utilization_percentage": 0.28,
      "peak_occupancy": 971,
      "peak_utilization_percentage": 0.72
    },
    {
      "timestamp": "2025-12-02T00:00:00Z",
      "window_start": "2025-12-02T00:00:00Z",
      "window_end": "2025-12-02T23:59:59Z",
      "avg_occupancy": 414,
      "avg_utilization_percentage": 0.31,
      "peak_occupancy": 1001,
      "peak_utilization_percentage": 0.75
    },
    {
      "timestamp": "2025-12-03T00:00:00Z",
      "window_start": "2025-12-03T00:00:00Z",
      "window_end": "2025-12-03T23:59:59Z",
      "avg_occupancy": 523,
      "avg_utilization_percentage": 0.39,
      "peak_occupancy": 1212,
      "peak_utilization_percentage": 0.9
    }
  ],
  "pagination": {
    "prev_cursor": null,
    "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2OH0",
    "has_more": true
  }
}

Get Traffic metrics for a location

get

Returns visits for a specific location over a given date range and interval. Traffic represents the total number of people who entered the location during each interval window. Supports optional hour and day filters for all intervals.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

The ID of the location.

Example: 1560

Query parameters

start_datestring · dateRequired

The start date of the requested time range in YYYY-MM-DD format.

Example: 2025-12-01

end_datestring · dateRequired

The end date of the requested time range in YYYY-MM-DD format.

Example: 2025-12-03

intervalstring · enumOptional

The time interval to aggregate traffic data by. Defaults to daily if not specified.

Default: dailyExample: dailyPossible values:

limitintegerOptional

Maximum number of data points to return per page. Defaults to 1000 if not specified.

Default: 1000Example: 3

cursorstringOptional

Cursor value from the previous response's pagination object used to fetch the next or previous page of results.

Example: eyJsb2NhdGlvbl9pZCI6MTU2OH0

start_hour_filterinteger · max: 23Optional

Filter data to only include readings at or after this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.

Example: 9

end_hour_filterinteger · max: 23Optional

Filter data to only include readings before or at this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.

Example: 17

days_filterstringOptional

Filter data to only include specific days of the week. Provided as a string of day codes with no separator where 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday. For example '23456' means Monday through Friday. Only supported for daily, weekly, and monthly intervals.

Example: 23456Pattern: ^[1-7]+$

Responses

200

Traffic metrics for the location

application/json

location_idintegerRequired

The ID of the location.

Example: 1560

namestringRequired

The name of the location.

Example: Austin Office

capacityintegerRequired

The total capacity of the location.

Example: 1341

metricstringRequired

The metric type returned.

Example: traffic

intervalstring · enumRequired

The time interval used to aggregate the data.

Example: dailyPossible values:

days_of_weekinteger[]Required

The days of the week included in the response data. Reflects the days_filter parameter if provided, otherwise includes all days. 1=Sunday through 7=Saturday.

Example: [2,3,4,5,6]

400

Bad request — one or more request parameters are invalid

application/json

404

Location not found or not accessible with the provided credentials

application/json

500

Internal server error

application/json

get

/locations/{id}/traffic

GET /v2/locations/{id}/traffic?start_date=2025-12-01&end_date=2025-12-03 HTTP/1.1
Host: api.occuspace.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "location_id": 1560,
  "name": "Austin Office",
  "capacity": 1341,
  "metric": "traffic",
  "interval": "daily",
  "time_range": {
    "start": "2025-12-01T00:00:00Z",
    "end": "2025-12-07T23:59:59Z"
  },
  "days_of_week": [
    2,
    3,
    4,
    5,
    6
  ],
  "hour_range": {
    "start": 0,
    "end": 17
  },
  "data": [
    {
      "timestamp": "2025-12-01T00:00:00Z",
      "window_start": "2025-12-01T00:00:00Z",
      "window_end": "2025-12-01T23:59:59Z",
      "traffic": 661
    },
    {
      "timestamp": "2025-12-02T00:00:00Z",
      "window_start": "2025-12-02T00:00:00Z",
      "window_end": "2025-12-02T23:59:59Z",
      "traffic": 745
    },
    {
      "timestamp": "2025-12-03T00:00:00Z",
      "window_start": "2025-12-03T00:00:00Z",
      "window_end": "2025-12-03T23:59:59Z",
      "traffic": 843
    }
  ],
  "pagination": {
    "prev_cursor": null,
    "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2OH0",
    "has_more": true
  }
}

Get Dwell Time metrics for a location

get

Returns historical dwell time metrics for a specific location over a given date range and interval. Dwell time represents how long people stayed in the location during each interval window, expressed in seconds. Supports optional hour and day filters for all intervals.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

The ID of the location.

Example: 1560

Query parameters

start_datestring · dateRequired

The start date of the requested time range in YYYY-MM-DD format.

Example: 2025-12-01

end_datestring · dateRequired

The end date of the requested time range in YYYY-MM-DD format.

Example: 2025-12-03

intervalstring · enumOptional

The time interval to aggregate dwell time data by. Defaults to daily if not specified.

Default: dailyExample: dailyPossible values:

limitintegerOptional

Maximum number of data points to return per page. Defaults to 1000 if not specified.

Default: 1000Example: 3

cursorstringOptional

Cursor value from the previous response's pagination object used to fetch the next or previous page of results.

Example: eyJsb2NhdGlvbl9pZCI6MTU2OH0

start_hour_filterinteger · max: 23Optional

Filter data to only include readings at or after this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.

Example: 9

end_hour_filterinteger · max: 23Optional

Filter data to only include readings before or at this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.

Example: 17

days_filterstringOptional

Filter data to only include specific days of the week. Provided as a string of day codes with no separator where 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday. For example '23456' means Monday through Friday. Only supported for daily, weekly, and monthly intervals.

Example: 23456Pattern: ^[1-7]+$

Responses

200

Dwell time metrics for the location

application/json

location_idintegerRequired

The ID of the location.

Example: 1560

namestringRequired

The name of the location.

Example: Austin Office

capacityintegerRequired

The total capacity of the location.

Example: 1341

metricstringRequired

The metric type returned.

Example: dwell_time

intervalstring · enumRequired

The time interval used to aggregate the data.

Example: dailyPossible values:

days_of_weekinteger[]Required

The days of the week included in the response data. Reflects the days_filter parameter if provided, otherwise includes all days. 1=Sunday through 7=Saturday.

Example: [2,3,4,5,6]

400

Bad request — one or more request parameters are invalid

application/json

404

Location not found or not accessible with the provided credentials

application/json

500

Internal server error

application/json

get

/locations/{id}/dwell_time

GET /v2/locations/{id}/dwell_time?start_date=2025-12-01&end_date=2025-12-03 HTTP/1.1
Host: api.occuspace.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "location_id": 1560,
  "name": "Austin Office",
  "capacity": 1341,
  "metric": "dwell_time",
  "interval": "daily",
  "time_range": {
    "start": "2025-12-01T00:00:00Z",
    "end": "2025-12-07T23:59:59Z"
  },
  "days_of_week": [
    2,
    3,
    4,
    5,
    6
  ],
  "hour_range": {
    "start": 0,
    "end": 17
  },
  "data": [
    {
      "timestamp": "2025-12-01T00:00:00Z",
      "window_start": "2025-12-01T00:00:00Z",
      "window_end": "2025-12-01T23:59:59Z",
      "avg_dwell_time": 241,
      "peak_dwell_time": 312
    },
    {
      "timestamp": "2025-12-02T00:00:00Z",
      "window_start": "2025-12-02T00:00:00Z",
      "window_end": "2025-12-02T23:59:59Z",
      "avg_dwell_time": 211,
      "peak_dwell_time": 301
    },
    {
      "timestamp": "2025-12-03T00:00:00Z",
      "window_start": "2025-12-03T00:00:00Z",
      "window_end": "2025-12-03T23:59:59Z",
      "avg_dwell_time": 232,
      "peak_dwell_time": 351
    }
  ],
  "pagination": {
    "prev_cursor": null,
    "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2OH0",
    "has_more": true
  }
}

Get Availability metrics for a location

get

Returns historical availability metrics for a specific location over a given date range and interval. Availability represents the percentage of time the location was unoccupied during each interval window. Null values indicate no data was available for that window, typically on days outside operating hours. Supports optional hour and day filters for daily, weekly, and monthly intervals.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

The ID of the location.

Example: 7444

Query parameters

start_datestring · dateRequired

The start date of the requested time range in YYYY-MM-DD format.

Example: 2025-12-01

end_datestring · dateRequired

The end date of the requested time range in YYYY-MM-DD format.

Example: 2025-12-03

intervalstring · enumOptional

The time interval to aggregate availability data by. Defaults to daily if not specified.

Default: dailyExample: dailyPossible values:

limitintegerOptional

Maximum number of data points to return per page. Defaults to 1000 if not specified.

Default: 1000Example: 3

cursorstringOptional

Cursor value from the previous response's pagination object used to fetch the next or previous page of results.

Example: eyJsb2NhdGlvbl9pZCI6MTU2OH0

start_hour_filterinteger · max: 23Optional

Filter data to only include readings at or after this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.

Example: 9

end_hour_filterinteger · max: 23Optional

Filter data to only include readings before or at this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.

Example: 17

days_filterstringOptional

Filter data to only include specific days of the week. Provided as a string of day codes with no separator where 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday. For example '23456' means Monday through Friday. Only supported for daily, weekly, and monthly intervals.

Example: 23456Pattern: ^[1-7]+$

Responses

200

Availability metrics for the location

application/json

location_idintegerRequired

The ID of the location.

Example: 7444

namestringRequired

The name of the location.

Example: Conference Room 100

capacityintegerRequired

The total capacity of the location.

Example: 6

metricstringRequired

The metric type returned.

Example: availability

intervalstring · enumRequired

The time interval used to aggregate the data.

Example: dailyPossible values:

days_of_weekinteger[]Required

The days of the week included in the response data. Reflects the days_filter parameter if provided, otherwise includes all days. 1=Sunday through 7=Saturday.

Example: [2,3,4,5,6]

400

Bad request — one or more request parameters are invalid

application/json

404

Location not found or not accessible with the provided credentials

application/json

500

Internal server error

application/json

get

/locations/{id}/availability

GET /v2/locations/{id}/availability?start_date=2025-12-01&end_date=2025-12-03 HTTP/1.1
Host: api.occuspace.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "location_id": 7444,
  "name": "Conference Room 100",
  "capacity": 6,
  "metric": "availability",
  "interval": "daily",
  "time_range": {
    "start": "2025-12-01T00:00:00Z",
    "end": "2025-12-07T23:59:59Z"
  },
  "days_of_week": [
    2,
    3,
    4,
    5,
    6
  ],
  "hour_range": {
    "start": 0,
    "end": 17
  },
  "data": [
    {
      "timestamp": "2025-12-01T00:00:00Z",
      "window_start": "2025-12-01T00:00:00Z",
      "window_end": "2025-12-01T23:59:59Z",
      "availability_percentage": 0.29
    },
    {
      "timestamp": "2025-12-02T00:00:00Z",
      "window_start": "2025-12-02T00:00:00Z",
      "window_end": "2025-12-02T23:59:59Z",
      "availability_percentage": 0.5
    },
    {
      "timestamp": "2025-12-03T00:00:00Z",
      "window_start": "2025-12-03T00:00:00Z",
      "window_end": "2025-12-03T23:59:59Z",
      "availability_percentage": 0.41
    }
  ],
  "pagination": {
    "prev_cursor": null,
    "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2OH0",
    "has_more": true
  }
}

hashtagGet Occupancy metrics for a location

hashtagGet Traffic metrics for a location

hashtagGet Dwell Time metrics for a location

hashtagGet Availability metrics for a location

Get Occupancy metrics for a location

Get Traffic metrics for a location

Get Dwell Time metrics for a location

Get Availability metrics for a location