# 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="https://3289302098-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe3YixUK5tCcflJxye0bT%2Fuploads%2Fgit-blob-746a92f53c57249620d5b889327d3edacb75d792%2Ftraffic%20mode_room.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>

{% 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>