/reports:query

`POST /reports:query`

http POST https://api.fyma.ai/reports:query < request.json

Headers

Header	Allowed values	Default
Accept	`application/json`, `text/csv`	`application/json`

Request body

Property	Type	Notes
aggregations	Aggregation[]
filters?	Filter[]
nestedFilters?	NestedFilter[]
splitInterval?	string	See split interval

Document models

Use this as a reference to which fields you can use in filters and aggregations.

Movement events

Field	Type	Description
trackingCameraId	string	ID of the camera
label	string	Object class (car, person, truck etc.)
crossedPaths.id	string	Name of the line crossed
crossedPaths.end	string	Direction of the object (A or B)
crossedPaths.start	string	Deprecated, as it's the inverse value of `crossedPaths.end`
polygons.id	string	Name of the polygon visited
polygons.value	number	Time spent in the polygon
timestamp	Date	Time when this event occurred

Both crossedPaths and polygons are nested documents, containing 0 ore more items for each line crossed or polygon visited, respectively.

Parking lot stats

Field	Type	Description
parkingLotId	string	ID of the parking lot
occupied	number	How many of the defined spots were occupied
free	number	How many of the defined spots were free
total	number	Total number of defined spots
timestamp	Date	Time when this measurement occurred

Parking events

Field	Type	Description
parkingLotId	string	ID of the parking lot
cameraId	string	ID of the camera that recorded the event
duration	number	Duration of the parking
spotId	string	ID of the parking spot
startingTimestamp	Date	Timestamp of when did the parking start
timestamp	Date	Timestamp of when did the parking end

NestedFilter

Filters document by nested documents (such as crossedPaths and polygons).

Property	Type
path	string
filters	Filter[]

Filters

Filter

One of TermsFilter, RangeFilter.

TermsFilter

Filters documents by terms. Useful for filtering by label, crossed line, polygon etc.

Property	Type	Notes
type	`terms`
field	string	See document models
values	string[]

RangeFilter

Filters documents by range. Useful for filtering by timestamp or any numerical value (e.g. time spent in polygon).

Property	Type	Notes
type	`range`
field	string	See document models
from	number
to	number

Aggregations

Aggregation

One of TermsAggregation, StatsAggregation, DateHistogramAggregation, FilterAggregation, NestedAggregation, FiltersAggregation, ReverseNestedAggregation.

All aggregation also have common properties:

Property	Type	Notes
keyJoiner?	string	Example on usage

DateHistogramAggregation

Property	Type	Allowed values
type	`dateHistogram`
field	string	`timestamp`
interval	string

interval property refers to the fixed interval property.

TermsAggregation

Property	Type	Notes
type	`terms`
field	string	See document models

StatsAggregation

Property	Type	Default	Notes
type	`terms`
field	string		See document models
min?	boolean	false
max?	boolean	false
avg?	boolean	true
sum?	boolean	false
count?	boolean	false

Split interval

Splits a timeseries query into smaller queries so you can aggregate over a longer timeframe.

String format: <amount: integer><unit: s|m|d|w|M|q|y>

Unit	Meaning
s	seconds
m	minutes
d	days
w	weeks
M	months
q	quarters
y	years

Technical details

For technical reasons implied by Elasticsearch, an aggregation pipeline cannot exceed a certain number of buckets it generates. When that happens, Elasticsearch responds with a "too many buckets" error.

You usually get this error when the aggregation pipeline contains too many aggregations over a long time range (e.g. group data with an interval of 15 minutes over a year).

To work around that, you can use the splitInterval parameter. However, split interval functionality only supports time series data which is bound by a range filter, meaning that the aggregation pipeline

must start with a dateHistogram aggregation and
contain a range filter, whose field parameter equals timestamp and contains from and to parameters.

{
  "aggregations": [
    // highlight-start
    {
      "type": "dateHistogram",
      "interval": "1d"
    }
    // highlight-end
    /* ... */
  ],
  "filters": [
    // highlight-start
    {
      "type": "range",
      "field": "timestamp",
      "from": "2022-12-28T08:11:12.253Z",
      "to": "2023-01-04T08:11:12.253Z"
    }
    // highlight-end
    /* ... */
  ]
}

Movement data examples

Group by day, then count by label

This query shows how many times a camera has seen different types of objects daily.

{
  "aggregations": [
    {
      "type": "dateHistogram",
      "interval": "1d"
    },
    {
      "type": "terms",
      "field": "label"
    }
  ],
  "filters": [
    {
      "type": "range",
      "field": "timestamp",
      "from": "2022-12-27T12:19:35.479Z",
      "to": "2023-01-03T12:19:35.480Z"
    }
  ]
}

[
  {
    "timestamp": "2022-12-27T00:00:00.000Z",
    "car": 323034,
    "person": 230671,
    "motorbike": 80413,
    "van": 69820,
    "truck": 23232,
    "bus": 15658,
    "adult": 12942,
    "tractor": 7312,
    "bicycle": 5460,
    "child": 3258
  },
  /* ... */
  {
    "timestamp": "2023-01-03T00:00:00.000Z",
    "car": 298641,
    "person": 205503,
    "van": 76742,
    "motorbike": 55508,
    "truck": 29261,
    "bus": 15082,
    "adult": 13763,
    "tractor": 7984,
    "bicycle": 5891,
    "child": 3465
  }
]

Group by day, then group by label, then count by crossed line

{
  "aggregations": [
    {
      "type": "dateHistogram",
      "interval": "1d"
    },
    {
      "type": "terms",
      "field": "label",
      "keyJoiner": "; "
    },
    {
      "type": "nested",
      "path": "crossedPaths"
    },
    {
      "type": "terms",
      "field": "crossedPaths.id"
    }
  ],
  "filters": [
    {
      "type": "range",
      "field": "timestamp",
      "from": "2022-12-27T12:21:51.464Z",
      "to": "2023-01-03T12:21:51.464Z"
    }
  ]
}

[
  {
    "timestamp": "2022-12-27T00:00:00.000Z",
    "car; Vehicle Traffic": 3212,
    "car; Road": 43243,
    "person; Entrance 1": 432
  },
  /* ... */
  {
    "timestamp": "2023-01-03T00:00:00.000Z",
    "car; Vehicle Traffic": 11566,
    "car; Road": 9049,
    "person; Entrance 1": 4098,
    "person; Entrance 2": 3815
  }
]

Note the use of keyJoiner. It can make the data more machine-readable. Without it, data series would be car Road, person Entrance and so on.

Group by day, then group by crossed line, then count by direction

{
  "aggregations": [
    {
      "type": "dateHistogram",
      "interval": "1d"
    },
    {
      "type": "nested",
      "path": "crossedPaths"
    },
    {
      "type": "terms",
      "field": "crossedPaths.id"
    },
    {
      "type": "terms",
      "field": "crossedPaths.end"
    }
  ],
  "filters": [
    {
      "type": "range",
      "field": "timestamp",
      "from": "2022-12-28T08:11:12.253Z",
      "to": "2023-01-04T08:11:12.253Z"
    }
  ]
}

[
  {
    "timestamp": "2022-12-28T00:00:00.000Z",
    "Vehicle Traffic B": 14853,
    "Vehicle Traffic A": 13717,
    "Road B": 9153,
    "Road A": 5492
  },
  /* ... */
  {
    "timestamp": "2023-01-04T00:00:00.000Z",
    "Road B": 4742,
    "Road A": 2533,
    "Entrance Total A": 5790,
    "Entrance Total B": 802
  }
]

Group by polygon, calculate stats of time spent in each polygon

{
  "aggregations": [
    {
      "type": "nested",
      "path": "polygons"
    },
    {
      "type": "terms",
      "field": "polygons.id"
    },
    {
      "type": "stats",
      "field": "polygons.value",
      "sum": true,
      "avg": true
    }
  ],
  "filters": [
    {
      "type": "range",
      "field": "timestamp",
      "from": "2022-12-28T08:39:24.466Z",
      "to": "2023-01-04T08:39:24.466Z"
    }
  ]
}

{
  "Dwell Time avg": 6.021585194493631,
  "Dwell Time sum": 1054198.92,
  "Parking avg": 41.076890402920846,
  "Parking sum": 2520149.38
}