Segment Filters
Introduction to Segments
Segments are a set of location based rules. They are created using the Segment Filters API and then referenced by ID in the Segment Queries API to get lists of devices that match the segment or setup callbacks.
Filters are the building block of segments. A filter may look like the following:
Present in Region A between 14:00 21/02/2019 and 16:00 21/02/2019
Filters can then be combined in a Segment, where either all of the filters must be met or any of them can be met:
Any
Present in Region A between 14:00 21/02/2019 and 16:00 21/02/2019
Present in Region A between 14:00 22/02/2019 and 16:00 22/02/2019
There is no limit to the number of Filters than can part of a Segment. Segments can be created and then used in other segments:
Segment A
Any
Present in Region A between 14:00 21/02/2019 and 16:00 21/02/2019
Present in Region A between 14:00 22/02/2019 and 16:00 22/02/2019
Segment B
Any
Present in Region B between 14:00 21/02/2019 and 16:00 21/02/2019
Present in Region B between 14:00 22/02/2019 and 16:00 22/02/2019
Segment C
All
Segment A
Segment B
This Segment will be true for a device if it visits Region A on either the 21st or the 22nd and it visits Region B on either the 21st or the 22nd.
Filter Options
| Name | Description | Other Parameters |
|---|---|---|
| IN_NOW | Devices that are currently in a region | regionId |
| OUT_NOW | Devices that are currently not in a region. Must always be combined with an ‘IN’ type. | regionId |
| IN_AT | Devices that were in the region at the given time | regionId, atTime |
| OUT_AT | Devices that were not in the region at the given time. Must always be combined with an ‘IN’ type | regionId, atTime |
| IN_BETWEEN | Devices that were in the region at some point between the two given times | regionId, from, to, minDwell (optional) |
| OUT_BETWEEN | Devices that were not in the region at any point between the two given times | regionId, from, to |
| ENTERED_BETWEEN | Devices that entered the region between the two given times | regionId, from, to |
| EXITED_BETWEEN | Devices that exited the region between the two given times | regionId, from, to |
| ENTERED | Devices that enter the region. This should only be used for triggered messages / callbacks. | regionId |
| EXITED | Devices that exit the region. This should only be used for triggered messages / callbacks. | regionId |
Segment Properties
| Name | Type | Description |
|---|---|---|
| id | String | The segment ID. This is not required (and will be ignored) on creation. It is used when updating segments. |
| name | String | The name of the segment |
| segmentType | String | The type of segment, ANY or ALL (the docs reference IN_ORDER and NUMBER_OF but they are no longer supported) |
| filters | Array of Filters | The filters that make up the segment |
| segmentIds | Array of Strings | IDs of other segments being used as part of this segment |
| orderedIds | Array of Strings | A list of the filter IDs and segment IDs |
| hidden | Boolean | This is used in the Colocator UI to hide / show segments in the list |
Filter Properties
| Name | Type | Description |
|---|---|---|
| id | String | The filter ID, must be generated as a gen 4 UUID |
| filterType | String | One of the filter types listed above |
| regionId | String | The ID of the region being used |
| atTime | String | A timestamp for use with AT type filters |
| from | String | A timestamp for use with BETWEEN type filters |
| to | String | A timestamp for use with BETWEEN type filters |
| minDwell | String | A dwell time in milliseconds that the device has to be present. Only used with the IN_BETWEEN type. |