Skip to main content

Querying Events

The EPCIS Query interfaces allow you to retrieve captured event data from TrackVision using GS1 EPCIS 2.0 compliant query methods.

Query REST API​

The EPCIS 2.0 Query REST API provides a standardized way to query for EPCIS events using RESTful endpoints.

Base Query Endpoint​

GET https://epcis.yourdomain.trackvision.ai/v2/epcis/events

Replace yourdomain with your actual TrackVision subdomain.

Query Parameters​

The Query REST API supports various parameters from the official EPCIS 2.0 query language to filter and retrieve specific events. The table below lists TrackVision's current extent of support. If you need a parameter not currently supported, contact us and it will be added promptly in the next release cycle.

ParameterDescriptionSupported
eventTypeFilters events by their type (e.g., ObjectEvent, AggregationEvent)Yes
GE_eventTimeFilters events with eventTime greater than or equal to a given timeYes
LT_eventTimeFilters events with eventTime less than a given timeYes
GE_recordTimeFilters events with recordTime greater than or equal to a given timeYes
LT_recordTimeFilters events with recordTime less than a given timeYes
EQ_actionFilters events by action (e.g., ADD, DELETE, OBSERVE)Yes
EQ_bizStepFilters events by business stepYes
EQ_dispositionFilters events by dispositionYes
EQ_persistentDisposition_setFilters events by set persistent disposition valuesContact us
EQ_persistentDisposition_unsetFilters events by unset persistent disposition valuesContact us
EQ_quantityFilters events with quantity equal to specified valueYes
GT_quantityFilters events with quantity greater than a specified valueYes
GE_quantityFilters events with quantity greater than or equal to specified valueYes
LT_quantityFilters events with quantity less than specified valueYes
LE_quantityFilters events with quantity less than or equal to specified valueYes
EQ_readPointFilters events by read point locationYes
WD_readPointFilters events with a descendant read pointContact us
EQ_bizLocationFilters events by business locationYes
WD_bizLocationFilters events with a descendant business locationYes
EQ_transformationIDFilters transformation events by their transformation IDYes
MATCH_epcFilters events that include a specific EPCYes
MATCH_parentIDFilters events with a specific parent IDYes
MATCH_inputEPCFilters transformation events with a specific input EPCYes
MATCH_outputEPCFilters transformation events with a specific output EPCYes
MATCH_anyEPCFilters events with any matching EPCYes
MATCH_epcClassFilters events with a specific EPC classYes
MATCH_inputEPCClassFilters transformation events with a specific input EPC classYes
MATCH_outputEPCClassFilters transformation events with a specific output EPC classYes
MATCH_anyEPCClassFilters events with any matching EPC classYes
EQ_eventIDFilters events by their unique event IDYes
EXISTS_errorDeclarationFilters events based on presence of error declarationsContact us
GE_errorDeclaration_TimeFilters events with error declarations after or on specified timeContact us
LT_errorDeclaration_TimeFilters events with error declarations before specified timeContact us
EQ_errorReasonFilters error declarations by reason codeContact us
EQ_correctiveEventIDFilters error declarations by corrective event IDContact us
orderBySpecifies the field to order the results byYes
orderDirectionSpecifies sort direction: ASC or DESCYes
eventCountLimitLimits the number of events in the resultContact us
maxEventCountMaximum number of events to returnContact us
EXISTS_sensorElementListFilters events with or without sensor dataContact us
GE_timeFilters events with sensor data time field greater or equal to specified valueContact us
LT_timeFilters events with sensor data time field less than specified valueContact us
GE_startTimeFilters events with sensor data startTime greater or equal to specified valueContact us
LT_startTimeFilters events with sensor data startTime less than specified valueContact us
GE_endTimeFilters events with sensor data endTime greater or equal to specified valueContact us
LT_endTimeFilters events with sensor data endTime less than specified valueContact us
EQ_typeFilters events with sensor data sensor report typeContact us
EQ_deviceIDFilters events with sensor data by device IDContact us
EQ_dataProcessingMethodFilters by method used for processing sensor dataContact us
EQ_microorganismFilters sevents with sensor data by microorganismContact us
EQ_chemicalSubstanceFilters events with sensor data by chemical substanceContact us
EQ_bizRulesFilters events with sensor data by business rulesContact us
EQ_stringValueFilters events with sensor data by stringValueContact us
EQ_booleanValueFilters events with sensor data by boolean valueContact us
EQ_hexBinaryValueFilters events with sensor data by hexBinary valuesContact us
EQ_uriValueFilters events with sensor data by URI valuesContact us
GE_percRankFilters events with sensor data with percRank greater or equal to specified valueContact us
LT_percRankFilters events with sensor data with percRank less than specified valueContact us
GT_percRankFilters events with sensor data with percRank greater than specified valueContact us
LE_percRankFilters events with sensor data with percRank less or equal to specified valueContact us

Example Query​

GET https://epcis.customer.trackvision.ai/v2/epcis/events?eventType=ObjectEvent&bizStep=shipping&perPage=50
Authorization: Bearer <your-token>

Query Response​

The query response follows the EPCIS 2.0 Query Schema specification:

{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"
  ],
  "type": "EPCISQueryDocument",
  "schemaVersion": "2.0",
  "creationDate": "2024-01-15T10:30:00.000Z",
  "epcisBody": {
    "queryResults": {
      "resultsBody": {
        "eventList": [
          {
            "type": "ObjectEvent",
            "eventTime": "2024-01-15T10:00:00.000Z",
            "eventTimeZoneOffset": "+00:00",
            "epcList": [
              "urn:epc:id:sgtin:0614141.812345.6789"
            ],
            "action": "OBSERVE",
            "bizStep": "shipping",
            "readPoint": {
              "id": "urn:epc:id:sgln:0614141.00777.0"
            }
          }
        ]
      }
    }
  }
}

Reusable Queries​

The EPCIS 2.0 standard allows the use of reusable "named" queries that can be saved and re-run over and over again. A named query creates a virtual collection of events (i.e., a view). It has a human-readable name and a query defined using the EPCIS query language. The result set of an EPCIS events query has the following URL pattern: /queries/{queryName}/events. A named query is created by specifying the query name, the type of query (EPCIS events or master data) and the query body. Once a query is created, clients can always retrieve the current set of resources that match the query description.

Creating Reusable Queries​

To create a saved query, POST to the queries endpoint with a JSON payload that follows the EPCIS standard. A name is required as is a query object. Example:

POST https://epcis.yourbrand.trackvision.ai/v2/epcis/queries
Content-Type: application/json
Authorization: Bearer <your-token>

{
 "name": "UniqueQueryName",
 "query": {
 "eventType": [
 "ObjectEvent"
 ],
 "EQ_bizStep": [
 "shipping",
 "receiving"
 ]
 }
}

Executing Reusable Queries​

To execute a saved query:

GET https://epcis.yourbrand.trackvision.ai/v2/epcis/queries/{queryName}/events
Authorization: Bearer <your-token>

Response is the same as a query response from the REST style endpoint.

Schema Validation​

All query responses are validated against the official EPCIS 2.0 Query Schema.

You can use this schema to:

  • Validate query responses in your application
  • Generate type definitions for strongly-typed languages