Office of Operations
21st Century Operations Using 21st Century Technologies

Appendix B. Cruise Detector User Guide


This manual describes how to use the GPS cruising identification model developed by FHWA. Any user with a working knowledge of GIS and simple database skills should be able to implement the system with the aid of information presented here. This tool uses GPS data to estimate the proportion of trips that are cruising for parking.

Software Requirements


Install PostgreSQL 13+, PostGIS 3.2+ along with pgrouting 3.3.0+. Using pgadmin 4 is also recommended. User will also need to install osm2po and Java 8+ to import a street network.

The following Python® packages must also be installed: numpy 1.11.3+ scipy 0.19.0+ pandas 0.19.2+ gpxpy 1.1.2+ psycopg2 2.5.2+ sqlalchemy 1.1.6+ docopt 0.6.1+

Create a base directory, and download the cruising and pgMapMatch repositories to that directory, and download the sample location data to the cruising folder. Add a folder titled “output” to store logs, and unzip the sampleLocationData folder if using. Download osm2po to a directory with no spaces in its path.

Data Requirements and Format

Street Network

The street network should be in pbf format. An extract for specific geographic areas can be obtained from The extract should be saved to the osm2po base path, if that is different from the project base bath.

Census Boundaries

Census tract or block group boundaries are used to aggregate results for analysis purposes after pgMapMatch has been run on the GPS trace data. Census geographies can be obtained in shapefile format from the U.S. Census Bureau’s TIGERweb database.

Global Positioning System Data

Location Data

Data formats may vary by vendor, but the raw GPS location data must be a table containing a minimum of: device ID, timestamp, latitude and longitude, and horizontal accuracy. The script is based on one specific vendor’s data and may require alteration to match the format and data structure of the location data obtained.

The following is an incomplete list of possible location data vendors*:

  • Vera set
  • Quadrant
  • Onemata
  • Lifesight

Trip Data

Trip data that have been pre-processed into traces by the vendor can also be used. The imported PostgreSQL table must contain:

  • trip_id: unique ID for each trace
  • lines_geom: Linestring M geometry of the trace
  • start_geom: Point M geometry of the start point
  • end_geom: Point M geometry of the end point

The following is an incomplete list of possible vendors for trip data*:

  • StreetLight
  • AirSage
  • TomTom

As with the location data, the list is not comprehensive, not an endorsement and not a guarantee the vendor will make usable data available. A collaboration with these firms may be necessary to access their data and information.

Config File Changes

User will need to change the configuration settings for Postgres, pgMapMatch, osm2po, and the cruising tool itself.

Postgres. After setting up the postgres database, removing the password requirement allows the tool to run smoother. This can be done by changing authentication requirements in the pg_hba.conf file to trust.

Clone the cruising and pgMapMatch repositories, and add a folder titled “output” to store logs.

cruising. Configuration parameters are located in the file. Open and set the parameters for host, file paths, regions, spatial reference systems, and number of CPU cores used for processing. The config file also contains multiple parameters to calibrate trace generation from GPS data and identify cruising.

pgMapMatch. Open and make changes to the pgInfo parameter for the postgres database connection. If password has been removed, make sure requirePassword is set to False. Save the file as

osm2po. Use the osm2po tool to import the OpenStreetMap data into the database. Make a couple of changes to the osm2po config file to accurately reflect turn restrictions and one-way streets:

postp.0.class =
postp.1.class = = true

Load the Data

To get started, create extensions for Postgis and Pgrouting by running the following query in the project's PostgreSQL database:


Next, run the following in Python IDE:

import sys
sys.path.append('[yourBasePath]/cruising') ## change this to your base path
from cruising import *
from cruising_importLocationData import *

Import Street Network

Run loadTables(region='[yourRegion]') with the respective region as specified in, which will import the osm street network and turn restriction table into the database. The field names for the streets table should match those in the pgMapMatch/ Make sure the SRS of the streets table matches the SRS to be used for the location or trip data, and create indexes and spatial indexes have been created. Depending on the imported network, it may improve performance to clip the street network to a convex hull around the study area.

To run the sample data, user will need to download the Washington State osm.pbf file to the osm2po path and run loadTables(region='wa'). The sample data are comprised of GPS point data, which will be used to generate traces, that can then be analyzed for cruising.

Import Census Boundaries

Use PostGIS to import the census boundary files to database, and reproject the data to the SRS being used. Use a spatial join to add the tract or block group ID to the streets table.

Import Global Positioning System Data

The script is based on a specific data vendor and may require alteration to match the format and data structure of the location data obtained.

To import the sample data, set the sample data directory and name for the imported location data table points_table and output trace table output_table.

Run the following code to import the table:

points_table = 'samplepoints'
trace_table = 'sampletraces'
iT = importTable(points_table, 'sampleLocationData', schema = 'public', region = 'wa', forceUpdate=True)

To generate traces from the sample data, run the following code:

pts = pointData(points_table, trace_table, schema = 'public', region = 'wa', forceUpdate=True)

Map-Matching from User-Generated Traces

Once the trace table is created, from either the sample data set or the user’s data, it can be mapmatched by running the following code:

trace_table = "[yourTraceTable]" ##same as the trace_table in the previous section
tt = traceTable(trace_table, schema = '[yourSchema]', region = '[yourRegion]', forceUpdate=True) ## change the table, schema, etc. 

This may take several hours, even with the sample data.

Results and Interpretation

Once the trips have been processed the data output can be analyzed with a spreadsheet, python, or any statistical package and GIS. See the data dictionary here:

Glossary for the Cruise Detector User Guide

A trail or path made up of a collection of chronologically arranged GPS locations.
A process to match a series of pings or traces to a street network or map.
Both a converter and a routing engine.
Displays information about processor groups hierarchy, its contents, and its characteristics.
A map-matching algorithm.
An extension that adds routing and other network analysis functionality to PostGIS/PostgreSQL databases.
A spatial database extender for PostgreSQL object-relational database.
Also known as Postgres, a free and open-source relational database management system emphasizing extensibility and SQL compliance.
To change the projection (coordinate system) of spatial data with another projection.
Spatial join
Involves matching rows from the Join Features to the Target Features based on their relative spatial locations.
A related or connected group of pings.

* The names of vendors in this list are included for informational purposes only and are not intended to reflect a preference, approval, or endorsement of any one product or entity. [ Return to Note * ]