Note
A quick word on naming conventions:
In future versions of the API, the gendered version of the counts attributes will be changed to more neutral language. This is not for reasons of political correctness, but rather to allow us to support additional count groups in a straight-forward way. The plan is to name each count group using an ascending letter of the alphabet (A,B,C.. etc).
Rather than use the old convention here, we’ve decided to already start using the new convention on new API endpoints. That way we hope to save you time in the long run.
In this case, for example, (maleUp, maleDown, femaleUp, femaleDown) -> (in_A, out_A, in_B, out_B)
Hourly Summary Endpoint
Much like the other summary endpoints, the hourly endpoint takes a venue_id and a date as parameters and returns an analyzed breakdown of each hour that given date.
- GET /api/1.0/hourlySummaries/{venue_id}/{YYYY}-{MM}-{DD}?interval_mode={strict|auto}
- Parameters:
venue_id – The ID of the venue to query
YYYY – Year
MM – Month (1-12)
DD – Date (1-31)
- Query Parameters:
interval_mode – (optional) Can be “strict” or “auto”. When unspecified, the default is “auto”: a new interval is started when a ‘reset’ event is encountered. When “strict”: each of the computed intervals is locked to the hourly marks.
- Response JSON Object:
id – generated ID for this hourly summary
venue – The id of the venue being queried
zone – The id of the zone being queried, -1 if the query is on the combined venue
date – interpreted date (yyyy-mm-dd form)
interval_mode – “strict” - each interval is exactly one hour in length, “auto” - new intervals are created by resets to better distingush pre- and post-reset input events
device_name_cache – a device_id-to-name dictionary based on the cached device name that was set during that day
intervals – Array of time intervals and their analysis, if strict is enabled then each interval is guaranteed to be a hour in duration. By default, a two intervals are created with each reset, one for the reset event in isolation (pay special attention to the end_count - remember that a reset may not return the global count to zero in multi-zone environments), and a second interval that spans to the natural interval end (i.e. the next round hour).
intervals[n].start_interval – unix timestamp for the start of this analyzed interval
intervals[n].end_interval – unix timestamp for the end of this analyzed interval
intervals[n].human_interval – String with human-comprehensible version of ‘start - end’ form (accurate to minute, provided for convenience). In “auto” interval mode (default), a reset interval will show “RESET @ {human_time}”.
intervals[n].contains_reset – Was the count reset during this interval? In
strictmode this can explain why the global counts don’t match the number of ins/outs counted during this interval.intervals[n].zones_reset – An array containing the ids for the zones that were reset during this interval
intervals[n].event_count – The number of stored events included in this interval
intervals[n].start_count – dictionary containing (A/male/blue total count, B/female/pink total count, and global total/A+B count) at the start of the this interval
intervals[n].end_count – dictionary containing (A/male/blue total count, B/female/pink total count, and global total/A+B count) at the end of the this interval
intervals[n].this_interval – dictionary containing ‘in’s and ‘out’s that occured from the start of the day until the end of this interval. These values correspond to each of the device buttons, with ‘A’ values being related to the blue/male count, and ‘B’ values being the pink/female count.
intervals[n].cumulative – Like
this_interval, but the the counts only include the in/out counts for this intervalintervals[n].this_interval_by_device – a dictionary, containing the breakdown of in/out counts by device_id. If a device did not have any impact on this interval, it is not included.
e.g. Fetch hourly summary for
Venue 1for Jan 1, 2019
GET /api/1.0/hourlySummaries/1/2019-01-01 HTTP/1.1 apikey: 123456789
HTTP/1.1 200 OK Content-Type: application/json { "hourlySummary": { "id": "1_-1_2020-1-1", "venue": 1, "zone": -1, "date": "2020-1-1", "interval_mode": "auto", "intervals": [ { "start_interval": 1577898000, "end_interval": 1577899800, "human_interval": "12:00pm - 12:30pm", "contains_reset": false, "zones_reset": [], "event_count": 0, "start_count": { "A": 264, "B": 69, "total": 333 }, "end_count": { "A": 264, "B": 69, "total": 333 }, "this_interval": { "in_A": 0, "in_B": 0, "out_A": 0, "out_B": 0 }, "day_cumulative": { "in_A": 0, "in_B": 0, "out_A": 0, "out_B": 0 }, "this_interval_by_device": {} }, { "start_interval": 1577899800, "end_interval": 1577899800, "human_interval": "RESET @ 12:30pm", "contains_reset": true, "zones_reset": [ 1 ], "event_count": 1, "start_count": { "A": 264, "B": 69, "total": 333 }, "end_count": { "A": 112, "B": 7, "total": 119 }, "this_interval": { "in_A": 0, "in_B": 0, "out_A": 0, "out_B": 0 }, "day_cumulative": { "in_A": 0, "in_B": 0, "out_A": 0, "out_B": 0 }, "this_interval_by_device": { "1": { "in_A": 0, "in_B": 0, "out_A": 0, "out_B": 0, "issued_reset": true } } }, " ... " ], "device_name_cache": { "1": "Main Entrance" } } }
Hourly Summary for Zone
To fetch an hourly breakdown for an individual Zone/Area, the result is exactly the same as the root hourly endpoint, except that it includes the data for _only_ the zone indicated.
- GET /api/1.0/hourlySummaries/zone/{zone_id}/{YYYY}-{MM}-{DD}
- Parameters:
zone_id – The ID of the zone to query
YYYY – Year
MM – Month (1-12)
DD – Date (1-31)
- Query Parameters:
interval_mode – (optional) Can be “strict” or “auto”. When unspecified, the default is “auto”: a new interval is started when a ‘reset’ event is encountered. When “strict”: each of the computed intervals is locked to the hourly marks.