Dragonfruit Traffic Analysis Metrics API

Common API Guide (Required Reading)

This API reference assumes familiarity with Dragonfruit’s shared API conventions. Before implementing, please review the Dragonfruit Common API Guide, which covers base URLs, authentication and token refresh, customer scoping (customer_id), supported content types, pagination patterns (where applicable), and standard validation/error-handling behavior used across Dragonfruit APIs.

Overview

This document describes the REST APIs for extracting Traffic Analysis Metrics from Dragonfruit <Ask Matthew>

API Reference

POST /customer/{customer_id}/insights/generate_traffic_report

Generates time-bucketed traffic and related metrics for one or more sites within a specified date + time-of-day range.

Path parameters

Name	Type	Required
customer_id	integer	Yes

Request

Path Parameters

• customer_id (path): Customer identifier.

Request Body

Top-level object:

• config (object, required)

Inside config:

1) Sites Facet

• sites_facet.site_ids (array[int], required)
  List of internal site ID values.

2) Date Facet

• date_facet.dateRange (string, required): Use "custom".

• date_facet.custom.range (array[string], required)
  [start_date, end_date] in YYYY-MM-DD format.

3) Time Facet

• time_facet.timeOfDay (string, required): Use "custom".

• time_facet.custom.range (array[string], required)
  [start_time, end_time] in HH:MM:SS format.

4) Group By Facet

• group_by_facet.time.unit (string, required): "minutes" or "hours".

• group_by_facet.time.number (int, required): Interval size in the selected unit.

• group_by_facet.groupBys (array[string], required)
  Grouping keys. Example includes: "time", "site".

5) Metric Facet

• metrics_facet.metrics (array[string], required)
  Metrics to compute (multiple supported in one request). Supported values:

  • "entrances"

  • "dwell_time"

  • "transactions"

  • "occupancy"

  • "walk_bys"

6) Version

• version (string, required): "V2"

Sample Request

{
  "config": {
    "sites_facet": {
      "site_ids": [
        750
      ]
    },
    "date_facet": {
      "custom": {
        "range": [
          "2026-02-18",
          "2026-02-19"
        ]
      },
      "dateRange": "custom"
    },
    "time_facet": {
      "custom": {
        "range": [
          "09:00:00",
          "17:00:00"
        ]
      },
      "timeOfDay": "custom"
    },
   "group_by_facet": {
      "time": {
        "unit": "minutes",
        "number": 15
      },
      "groupBys": [
        "time",
        "site"
      ]
    },

    "metrics_facet": {
      "metrics": [
        "entrances"]
    },
    "version": "V2"
  }
}

Example (sites only)

curl -X POST \
  "$BASE_URL/customer/123/sites/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "sites=@sites.csv"

Example (sites + contacts)

curl -X POST \
  "$BASE_URL/customer/123/sites/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "sites=@sites.csv" \
  -F "site_contacts=@site_contacts.csv"

Response

What to read

The primary output is inside:

• data.InsightResponse.data (array of rows)

Each row corresponds to a time bucket (based on group_by_facet) for a site (based on groupBys).

Row Fields

Common fields in each row include:

• time (string)
  Start time of the interval in YYYY-MM-DD HH:MM:SS format.

• site_name (string)
  Name of the site linked to the provided site_id.

• metric fields (number)
  For each selected metric, the row contains a field with its value. Example:

  • "entrances": 19

Other fields may be present (example: entity_id, filter_id, region_names) but the core usage is typically driven by time, site_name, and the selected metric fields.

Example Response

{
  "data": {
    "Config": {
      ...
    },
    "InsightResponse": {
      "cached_data_ratio": 1,
      "computed_at": 1771513404.8116665,
      "data": [
        {
          "entity_id": "36655",
          "entrances": 19,
          "filter_id": "450e633b0b76a889eb487f6dfcd575cc",
          "region_names": [
            "Tyler"
          ],
          "site_name": "Tyler",
          "time": "2026-02-18 09:00:00"
        },
        {
          "entity_id": "36655",
          "entrances": 23,
          "filter_id": "450e633b0b76a889eb487f6dfcd575cc",
          "region_names": [
            "Tyler"
          ],
          "site_name": "Tyler",
          "time": "2026-02-18 09:15:00"
        },
        {
          "entity_id": "36655",
          "entrances": 15,
          "filter_id": "450e633b0b76a889eb487f6dfcd575cc",
          "region_names": [
            "Tyler"
          ],
          "site_name": "Tyler",
          "time": "2026-02-18 09:30:00"
        },
        {
          "entity_id": "36655",
          "entrances": 20,
          "filter_id": "450e633b0b76a889eb487f6dfcd575cc",
          "region_names": [
            "Tyler"
          ],
          "site_name": "Tyler",
          "time": "2026-02-18 09:45:00"
        },
        ...
        {
          "entity_id": "36655",
          "entrances": 17,
          "filter_id": "450e633b0b76a889eb487f6dfcd575cc",
          "region_names": [
            "Tyler"
          ],
          "site_name": "Tyler",
          "time": "2026-02-19 16:30:00"
        },
        {
          "entity_id": "36655",
          "entrances": 29,
          "filter_id": "450e633b0b76a889eb487f6dfcd575cc",
          "region_names": [
            "Tyler"
          ],
          "site_name": "Tyler",
          "time": "2026-02-19 16:45:00"
        }
      ],
      "is_data_truncated": false,
      "metadata": {
        ...
      },
      "site_mapping": {
        ...
      },
      "status": "success",
      "total_count": {}
    }
  },
  "success": true
}