Skip to main content

A toolkit for inferencing trips and trip metadata from Itinerum GPS data

Project description


Python Version

Documentation for library usage:

This library serves as a framework to process data from the Itinerum platform and hardware GPS loggers (e.g., QStarz). It can be used both through Jupyter to explore datasets interactively or imported as a module in standalone scripts and applications.

This repository also serves as the development bed for the Itinerum platform algorithms within the TRIP Lab repositories.



  1. Clone this repository and pip install -r requirements.txt (using a Python virtual environment is recommended)
  2. Place source .csv data in the itinerum-tripkit/input folder (create if necessary) and edit ./tripkit/ to reflect the correct filepaths.

Then either:

  • Start Jupyter in repository directly and get started by from tripkit import Itinerum


  • Copy the tripkit directory into other projects as a library (more complete packaging to come)

For more complete installation information, see the official itinerum-tripkit documentation.

Loading Subway Stations

Subway station data for trip detection can be loaded similarly for all processing modules. Place a .csv file of station entrances with the columns of x (or longitude) and y (or latitude). Locations are expected as geographic coordinates only. Edit the SUBWAY_STATIONS_FP config parameter to reflect the subway stations .csv filepath.


View attributes on a User

import tripkit_config
itinerum = Itinerum(tripkit_config)

# create a new database and read in .csv data

# load all users from database
users = itinerum.load_all_users()

test_user = users[0]

Run trip detection on a User

import tripkit_config
itinerum = Itinerum(tripkit_config)

# load user from database by uuid
user = itinerum.database.load_user('00000000-0000-0000-0000-000000000000')

# run a provided trip detection algorithm
parameters = {
    'subway_entrances': itinerum.database.load_subway_entrances(),
    'break_interval_seconds': tripkit_config.TRIP_DETECTION_BREAK_INTERVAL_SECONDS,
    'subway_buffer_meters': tripkit_config.TRIP_DETECTION_SUBWAY_BUFFER_METERS,
    'cold_start_distance': tripkit_config.TRIP_DETECTION_COLD_START_DISTANCE_METERS,
    'accuracy_cutoff_meters': tripkit_config.TRIP_DETECTION_ACCURACY_CUTOFF_METERS
trips =, parameters)


Trip Detection

parameters A dictionary to supply arbitrary kwargs to an algorithm
subway_stations A list of subway station entrance database objects containing latitude and longitude attributes
coordinates A timestamp-ordered list of coordinates as dicts for a specific user. Multiple users should be run in sequence and have their output coordinates concatenated into a single list after if desired.

Trip Outputs

Trips will be output with the following trip codes to indicate the type of trip:

Trip Code Description
1 Complete trip
2 Complete trip - subway
101 Missing trip
102 Missing trip - subway
103 Missing trip - less than 250m
201 Single point
202 Distance too short - less than 250m


The aim of this library is to provide easy visualization of Itinerum data to assist in writing trip processing algorthms. Therefore at a minimum, the library provides exporting processed coordinates and traces as .geojson files (TBA: GeoPackage format). With a PostgreSQL backend for caching, PostGIS can be enabled (unimplemented) and a geom column generated for directly connection QGIS to the output data. The library should also easily provide methods for easily plotting GPS within Jupyter notebooks.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

itinerum-tripkit-0.0.1.tar.gz (44.9 kB view hashes)

Uploaded source

Built Distribution

itinerum_tripkit-0.0.1-py3-none-any.whl (83.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page