Traccar

Traccar offers a free, open-source solution for researchers to gather GPS data from many participants. It achieves this through a robust client-server architecture, ensuring the security and reliability of your data collection process.

The system consists of two main components:

Traccar Server: This server-side application (runs on a computer) acts as a central hub, receiving data from participant devices. It also provides a web interface for researchers to configure the system and access collected information.
Traccar Client: This mobile application, available for Android and iOS, runs on participants' phones. It collects GPS data and sensor readings and then transmits them securely to the Traccar Server.

Traccar also offers API, which researchers can use with the LABDA package to download, parse, and integrate the collected data seamlessly into their analysis for in-depth exploration. Traccar simplifies the entire data collection and processing workflow for researchers.

For detailed information on Traccar server and client functionalities, visit their official website.

Limitations

Offline Buffering: If a phone loses connection, any GPS data collected during that time won't be saved. However, Traccar can temporarily store data on the device, but it might take over 24 hours to reach the server after reconnection.

Battery Drain: The client app can be pretty demanding on phone batteries. Participants might need to charge their phones more often to ensure uninterrupted tracking.

How to use it?

Below, we've outlined the steps to get started with Traccar.

Server

Info

This guide is for advanced users only. For most people, a cloud-based Traccar solution is easier to use. If you want to host your server at your institution, contact your IT department for assistance.

This docker-compose setup offers a simplified approach to launching the Traccar Server locally. It utilizes the built-in H2 database, allows customization through your configuration file, and directs logs to a designated folder.

docker-compose.yml

version: "3.9"

services:
  traccar:
    image: traccar/traccar:ubuntu
    container_name: traccar
    restart: unless-stopped
    ports:
      - 8082:8082
      - 5000-5150:5000-5150
      - 5000-5150:5000-5150/udp
    volumes:
      - ./logs:/opt/traccar/logs:rw
      - ./conf/traccar.xml:/opt/traccar/conf/traccar.xml:ro

To create a custom configuration file, refer to the provided template and list of customizable parameters.

Client

Download the mobile client apps for Android and iOS. To configure the app for your research project, you'll need to adjust these settings:

Service status: Enable/disable the data collection.
Device Identifier: This unique ID is crucial. The administrator must manually add your device to the Traccar server.
Server URL: Enter the web address of your Traccar server.
Location Accuracy: Set this to "High" for continuous GPS tracking. Other options rely on cell towers for location, which can be less precise.
Frequency (seconds): Choose how often location data is logged (ideally 15, 30, or 60 seconds).
Distance (meters): Leave this blank. It only sends data when the location changes by a set distance.
Angle (meters): Like distance, leave it blank for continuous updates.
Offline Buffering: Enable this to store data on the phone if there's no connection. It will be sent later (up to 24 hours).
Wake Lock: This prevents the phone from sleeping and ensures uninterrupted tracking.

Important Reminders

Allow the app to collect data in the background and make sure the app doesn't get automatically closed when idle.

labda.parsers.Traccar

from_server

from_server(
    url: str,
    username: str,
    password: str,
    subject_id: str,
    *,
    start: datetime | None = None,
    end: datetime | None = None,
    sampling_frequency: float | None = None,
    crs: str | None = "infer",
    timezone: str | None = "infer",
    sensor_id: str | None = None,
    vendor: Vendor = Vendor.TRACCAR,
    model: str | None = None,
    serial_number: str | None = None,
    firmware_version: str | None = None
) -> Subject

The Traccar API allows you to download data from a specific server (URL) using your login credentials (username and password). To obtain data for a particular device, you must specify a subject ID (which corresponds to the device identifier). Optionally, you can define a date and time range to download data for a specific timeframe. If no date range is provided (from/to), all data for the chosen device will be downloaded.

The downloaded data will be parsed and validated according to the schema defined in the structure module.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL of the Traccar server.	required
`username`	`str`	The username to authenticate with the server.	required
`password`	`str`	The password to authenticate with the server.	required
`subject_id`	`str`	The ID of the subject to fetch data for (corresponds to the device identifier).	required
`start`	`datetime`	The start time of the data to fetch. If not provided, it will fetch all available data.	`None`
`end`	`datetime`	The end time of the data to fetch. If not provided, it will fetch all available data.	`None`
`sampling_frequency`	`float`	The sampling frequency of the data. If not provided, it will be infered from data.	`None`
`timezone`	`str`	The timezone of the data. If set to "infer" it will be inferred from the data. If None it will be set to the local timezone. Otherwise, it will be set to the provided timezone.	`'infer'`
`crs`	`str`	The coordinate reference system (CRS) of the data. If set to "infer" it will be inferred from the data. If None it will be set to "EPSG:4326". Otherwise, it will be set to the provided CRS.	`'infer'`
`sensor_id`	`str`	The ID of the sensor to fetch data for. If not provided, unique device ID from Traccar server will be used (if available).	`None`
`vendor`	`Vendor`	The vendor of the device. Defaults to "Traccar".	`TRACCAR`
`model`	`str`	The model of the device. If not provided, it will be fetched from the Traccar server (device - extra, phone + model) if available.	`None`
`serial_number`	`str`	The serial number of the device.	`None`
`firmware_version`	`str`	The firmware version of the device.	`None`

Returns:

Name	Type	Description
`Subject`	`Subject`	A Subject object containing the fetched and processed dataframe containing information: datetime, latitude, longitude, gps_accuracy, distance, elevation, and speed.

Raises:

Type	Description
`HTTPError`	HTTP request to the Traccar server failed.
`ValueError`	No device is found for the specified subject ID.
`ValueError`	No records are found for the specified device.

Examples:

Here's how to call the function with just the minimum required parameters.

from labda.parsers import Traccar

subject = Traccar.from_server(
    url="http://gps.example.com",
    username="admin",
    password="pwd9000",
    subject_id="john_doe",
)