Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

OpenLR location dereferencer

Project description


License Build status Coverage Status PyPI - Python Version PyPI Documentation

This is a Python package for decoding OpenLR™ location references on target maps.

Its purpose is to give insights into this map-matching process.


  • Python ≥ 3.6
  • geographiclib (PyPi package)
  • shapely (PyPi package)
  • openlr (PyPi package)
  • For unittests: SpatiaLite


  • <input type="checkbox" disabled="" /> Decoding line locations
  • <input type="checkbox" disabled="" /> Decoding 'point along line' locations
  • <input type="checkbox" disabled="" /> Decoding 'POI with access point' locations


This package is divided into the following submodules:


Contains an abstract map class, which you may want to implement for your target map.

maps.wgs84 provides methods for reckoning with WGS84 coordinates.


Implements the abstract map class for the example map format used in the unittests and examples


The actual logic for matching references onto a map.

This includes finding candidate lines and scoring them, and assembling a dereferenced location.


Contains the observer class, allowing you to hook onto certain events in the decoding process.


This project is available on PyPi:

pip3 install openlr-dereferencer


The decode(reference, mapreader) function will take a location reference and return map objects.

Usage Example

First, implement the MapReader class for your map. The example_sqlite_map module is an implementation you may look at.

Second, construct a location reference. For instance, parse an OpenLR line location string:

from openlr import binary_decode
reference = binary_decode("CwmG8yVjzCq0Dfzr/gErRRs=")

Third, decode the reference on an instance of your map reader class:

from openlr_dereferencer import decode
real_location = decode(reference, mapreader)

real_location.lines # <- A list of map objects


The decode function takes in an optional Config object containing decoding settings. With it, you may specify the decoder's behaviour:

from openlr_dereferencer import decode, Config

my_config = Config(
    geo_weight = 0.66,
    frc_height = 0.17,
    fow_height = 0.17,
    bear_weight = 0.0

decode(reference, mapreader, config=my_config)


openlr-dereferencer logs all mapmatching decisions using the standard library logging module.

Use it to turn on debugging:

import logging



Via implementing the Observer interface, you can hook onto certain events happening while decoding, and inspect the situation:

from openlr_dereferencer import DecoderObserver, SimpleObserver

# Look at SimpleObserver for an example implementation
my_observer = SimpleObserver()
decode(reference, mapreader, observer=my_observer)

Development environment

Firstly create a Python virtual environment for the project.

python3 -m venv .venv

Activate the virtual environment.

source .venv/bin/activate

Install the dependency packages into the virtual environment.

pip install openlr geographiclib shapely

You may need to install the spatialite module for sqlite if this is not already present.

sudo apt install libsqlite3-mod-spatialite

To run the decoding tests.

python3 -m unittest tests.test_decode

More Documentation

You are welcomed to read the generated API documentation at

Project details

Download files

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

Files for openlr-dereferencer, version 1.1.1
Filename, size File type Python version Upload date Hashes
Filename, size openlr_dereferencer-1.1.1-py3-none-any.whl (31.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size openlr_dereferencer-1.1.1.tar.gz (19.1 kB) File type Source Python version None Upload date Hashes View

Supported by

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