API Data Formats & Output Targets

The API Data Formats & Output Targets editor allows you to edit the data that is exposed for your project via the Quuppa API. The sections below will introduce the different default API data formats that are already available to use, how to edit the formats for the needs of your project as well as how to create output targets.

For more detailed information about using the Quuppa API, please refer to our Quuppa Positioning Engine User Manual or the Quuppa API documentation, available via links in the Quuppa Positioning Engine (QPE) Web Console.

Available API Data Formats

Formats available in JSON and CSV

For Tags:

Applicable for tag output targets or for API endpoint /getTagData?format=<name-of-your-format>

DefaultInfo - Provides data points related to tag information such as tag state, tag group, battery level, button state, acceleration data, TX power, developer specific data. The format is for cases where you only require information about the tags in the project, e.g. an application for monitoring the battery levels and current states of the tags in a project.
DefaultLocation - Provides data points related to tag positioning information, such as location estimates, the coordinate systems, the tracking areas and zones. The format is for cases where you want to show the positioning information related to the project, e.g. applications that visualise how tags move around a space on a map.
DefaultLocationAndInfo - Provides a combination of tag information (e.g. tag states, tag groups, battery level, button state, acceleration data, TX power and developer specific data) and positioning information (e.g. location estimates, coordinate systems, tracking areas and zones). This format is for cases that require both types of data, e.g. applications where tag movements are shown on a map and actions triggered by pressing the tag button are also visualised in the map view.
ALL_ITEMS - Provides all available data points related to tag. This format is not intended for use as is, but provides all of the possible options to enable format customisations according to the needs of your project.

For Locator Data:

Applicable for locator output targets or for API endpoint /getLocatorData?format=<name-of-your-format>

defaultLocatorInfo - Provides all Locator related data points
legacyLocatorInfo - Provides all Locator related data points in the same formatting as they are in the API response for /getLocatorInfo (legacy API for locators)

For Positioning Engine Data:

Applicable for PE output targets or for API endpoint /getPEData?format=<name-of-your-format>

defaultPEInfo- Provides all Positioning Engine related data points

Note: If you have enabled Legacy Output Formats from the QSP application settings, you will also be able to see the following legacy formats: Location JSON, Location CVS, Tag info JSON, Tag info CSV, Processed location CSV. These legacy formats are deprecated, please use the default formats listed above instead.

Edit API Data Formats

The types of data that you want to expose via the Quuppa APIs will depend on the specific requirements of the project that you are working on. The API Data Formats & Output Targets editor enables the use of our default API format definitions (DefaultInfo, DefaultLocation, DefaultLocationAndInfo and ALL_ITEMS) as templates to customise to the needs of your project. JSON and CSV outputs are available for all of the output formats.

To edit the format definitions, please follow the steps below:

Open the project in the QSP.
In the menu bar at the top, open the Project menu and select API Data Formats (alternatively the editor can be accessed via the object tree on the left by clicking on API Data Formats). This will open the API Data Formats & Output Targets editor to the API Data Formats tab.
In the UDP/logging/API format definitions table, select the default definition that you would like to edit. For more information about the available options, please see the Available Formats section above.
Copy the default format by clicking on the Clone Format button under the definitions table. This will open a new format editor window.

Tip: We always recommend cloning the format that you intend to use, even if you don't want to edit the format string, as we are constantly working on improving our API and as such the default formats may change with future software releases.
Give the new format a name and edit the format string as needed. The window also shows the sample output strings in both JSON and CSV formats so you can check the output.
When you are ready, click the OK button at the bottom of the window to save the edits. The customised format and its ID will be made visible in the UDP/logging/API format definitions table.
Close the UDP/logging/API editor.

Next, you will need to Create Output Targets for where the data from the above defined format definitions is sent.

Create Output Targets

Targets define the destination for where the project data is sent or written. To define targets for your project, follow the steps below:

Open the project in the QSP.
In the menu bar at the top, open the Project menu and select Output Targets (alternatively the editor can be accessed via the object tree on the left by clicking on Output Targets). This will open the API Data Formats & Output Targets editor to the Output Targets tab.
In the editor, click on the Add output target button.
In the window that opens, give the target a name and select the settings that best match your requirements. For more information about the available options, please see the Target Settings section below.
Click the OK button once done. The new target will be added to the UDP/logging targets list. You can edit or delete targets as needed by using the buttons under the list.

Target Settings


Setting	Description	Options
Format	Select the output format for the target.	DefaultInfo
		DefaultLocation
		DefaultLocationAndInfo
		custom output format
Type	Select whether you would like the output in JavaScript object notation (JSON) or Comma-separated values (CSV) form.	JSON
Type		CVS
Trigger mode	Define when updates are triggered.	Interval (i.e. at predefined intervals, in seconds)
		LastSeenUpdate (any new packet is received from tag)
		LocationUpdate (new location is available)
		RawPositionUpdate (new raw position is available for tag)
		SmoothPositionUpdate (new smooth position is available for tag)
		KalmanPositionUpdate (new kalman position is available for tag)
		ButtonDownUpdate (new button down information is available for tag)
On Data Change	Optional, if set output is only produced if the value of the field specified has changed since previous output.	Uses the same $(field.attribute) annotation as Output Formats. (See ‘Output Formats’ section or Quuppa API Documentation for /getTagData) Example: $(location.ts) would mean that output is only produced if the Location estimate's timestamp is different that of previous output.
Max batch size	Optional, applicable for 'Interval' type target. Defines how many tags / locators are collected into a single message when outputting data.	Default value 1. Example: Value set to 1000 will collect at maximum 1000 tags / locators into a single message that is sent. If the number of tags / locators is more, multiple messages of max 1000 tags each will be sent on the specified interval. Note that large message size with UDP may cause the end of the message being cut away.
Target	Select whether data will be sent over UDP, MQTT or written in a file.	UDP: Set the target IP addressfor where the data will be sent. Set the target Port number for where the data will be sent.
		File: Set the Folder where the data file will be written. Define the Filename prefix for the file that will be written. Define the number of Entries per file that can be logged in the file. Select whether to Include header as first line of the file.
		MQTT: Required. Set the hostname or IP address of your MQTT server. Required. Set the communication port to be used. Required. Set the communication scheme to be used. Optional. Define a client ID for your MQTT publisher client. If client ID is left empty, the target name is used as the client ID. Optional. Set the username for authenticating the publisher client. Optional. Set the password for authenticating the publisher client.
Start at system start	The checkbox allows you to select whether data can be sent automatically from the moment that the system is started, e.g. after a system restarts caused by problems like power failures.	Selected
Start at system start		Not selected
Tag groups	Select whether the target will be defined for all tags, or just for specific tag groups.	All tags
Tag groups		Custom