Skip to main content

/reports:query

POST /reports:query

See Reporting engine for guides.

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

Headers

HeaderAllowed valuesDefault
Acceptapplication/json, text/csvapplication/json

Request body

PropertyTypeNotes
aggregationsAggregation[]
filters?Filter[]
nestedFilters?NestedFilter[]
splitInterval?stringSee split interval

Document models

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

Movement events

FieldTypeDescription
trackingCameraIdstringID of the camera
labelstringObject class (car, person, truck etc.)
crossedPaths.idstringName of the line crossed
crossedPaths.endstringDirection of the object (A or B)
crossedPaths.startstringDeprecated, as it's the inverse value of crossedPaths.end
polygons.idstringName of the polygon visited
polygons.valuenumberTime spent in the polygon
timestampDateTime 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

FieldTypeDescription
parkingLotIdstringID of the parking lot
occupiednumberHow many of the defined spots were occupied
freenumberHow many of the defined spots were free
totalnumberTotal number of defined spots
timestampDateTime when this measurement occurred

Parking events

FieldTypeDescription
parkingLotIdstringID of the parking lot
cameraIdstringID of the camera that recorded the event
durationnumberDuration of the parking
spotIdstringID of the parking spot
startingTimestampDateTimestamp of when did the parking start
timestampDateTimestamp of when did the parking end

NestedFilter

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

PropertyType
pathstring
filtersFilter[]

Filters

Filter

One of TermsFilter, RangeFilter.

TermsFilter

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

PropertyTypeNotes
typeterms
fieldstringSee document models
valuesstring[]

RangeFilter

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

PropertyTypeNotes
typerange
fieldstringSee document models
fromnumber
tonumber

Aggregations

Aggregation

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

All aggregation also have common properties:

PropertyTypeNotes
keyJoiner?stringExample on usage

DateHistogramAggregation

PropertyTypeAllowed values
typedateHistogram
fieldstringtimestamp
intervalstring

TermsAggregation

PropertyTypeNotes
typeterms
fieldstringSee document models

StatsAggregation

PropertyTypeDefaultNotes
typeterms
fieldstringSee document models
min?booleanfalse
max?booleanfalse
avg?booleantrue
sum?booleanfalse
count?booleanfalse

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>

UnitMeaning
sseconds
mminutes
ddays
wweeks
Mmonths
qquarters
yyears

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": [
{
"type": "dateHistogram",
"interval": "1d"
}
/* ... */
],
"filters": [
{
"type": "range",
"field": "timestamp",
"from": "2022-12-28T08:11:12.253Z",
"to": "2023-01-04T08:11:12.253Z"
}
/* ... */
]
}

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.

Request
{
"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"
}
]
}
Response
[
{
"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

Request
{
"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"
}
]
}
Response
[
{
"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
}
]
tip

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

Request
{
"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"
}
]
}
Response
[
{
"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

Request
{
"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"
}
]
}
Response
{
"Dwell Time avg": 6.021585194493631,
"Dwell Time sum": 1054198.92,
"Parking avg": 41.076890402920846,
"Parking sum": 2520149.38
}