> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/historical-occupancy/reporting-api-overview/traffic.md).

# Traffic

Traffic measures the flow of people entering and leaving a space. It tracks **entries (Ins)** and **exits (Outs)**, providing data that can be aggregated or filtered by floors, rooms, or zones. This metric relies on traffic sensors placed at key access points to monitor movement over time accurately.

<div align="left"><figure><img src="/files/KhmS8HBt7ZpLBEvJMzP8" alt="" width="375"><figcaption></figcaption></figure></div>

### Response fields

Traffic responses contain per-bucket counters and, since August 3, 2026, their cumulative counterparts:

| Field        | Meaning                                                                           |
| ------------ | --------------------------------------------------------------------------------- |
| `in`         | Entries counted during the time bucket                                            |
| `out`        | Exits counted during the time bucket                                              |
| `in_csum`    | Cumulative entries since the daily reset (local midnight, per the query timezone) |
| `out_csum`   | Cumulative exits since the daily reset                                            |
| `delta_sum`  | Net change during the bucket (`in − out`)                                         |
| `delta_csum` | Cumulative net change since the daily reset                                       |

The cumulative fields are additive — `in`/`out` values and semantics are unchanged. Use `in_csum` at the end of a day for the day's total entries without summing buckets yourself.

{% hint style="success" %}
**Recommended Practices**

1. **Traffic Metrics:** Use the `sum` function to aggregate the total entries and exits over the defined period.
2. **Avoid Relative Time Queries:** Do not use relative time functionality (e.g., `-5m`) as it may result in missing data depending on query timing. Always specify absolute ***start*** and ***stop*** times.
3. **Timezone Configuration:** Always provide a **timezone** when querying traffic-based occupancy
4. **Include Zero Values in Output:** To ensure zero values are included in the results, add the filter:

   ```json
   "filter": { "value": { "gte": 0 } }
   ```

{% endhint %}

#### Query the total hourly entrances and exits at a room or floor entrance.

{% hint style="info" %}
Use measurement: <mark style="color:purple;">**`traffic`**</mark>

Use function: <mark style="color:purple;">**`sum`**</mark>
{% endhint %}

<details>

<summary>Request</summary>

```json
// POST https://api.butlr.io/api/v3/reporting

{
    "window": {
        "every": "1h",
        "function": "sum",
        "timezone": "America/New_York" // replace with your timezone
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["traffic"],
        "rooms": {
            "eq": ["room_2qfewCOsBcP2ylz62KeUDgdr0Is"]
        }
    },
    "group_by": {
      "order": ["time", "field"]
    }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
  "data": {
    "2024-01-01T04:00:00": {
      "in": {
        "sum": 63, // total entrances over the hour
        "min": 3,
        "max": 10,
        "count": 9,
        "mean": 7,
        "median": 7,
        "stddev": 1.8856180831641267,
        "first": 3,
        "last": 6
      },
     "out": {
        "sum": 51, // total exits over the hour
        "min": 3,
        "max": 10,
        "count": 9,
        "mean": 7,
        "median": 7,
        "stddev": 1.8856180831641267,
        "first": 3,
        "last": 6
      }
    },
    "2024-01-01T05:00:00": {
      "in": {
        "sum": 12, // total entrances over the hour
        "min": 3,
        "max": 10,
        "count": 9,
        "mean": 7,
        "median": 7,
        "stddev": 1.8856180831641267,
        "first": 3,
        "last": 6
      },
     "out": {
        "sum": 17, // total exits over the hour
        "min": 3,
        "max": 10,
        "count": 9,
        "mean": 7,
        "median": 7,
        "stddev": 1.8856180831641267,
        "first": 3,
        "last": 6
      }
    },
    // ... more data
  }
}
```

</details>