mappymatch
Mappymatch is a pure-python package developed and open sourced by the National Renewable Energy Laboratory. It contains a collection of "Matchers" that enable matching a GPS trace (series of GPS coordinates) to a map.
The current matchers are:
LCSSMatcher: A matcher that implements the LCSS algorithm described in this paper. Works best with high resolution GPS traces.OsrmMatcher: A light matcher that pings an OSRM server to request map matching results. See the official documentation for more info.ValhallaMatcher: A matcher to ping a Valhalla server for map matching results.
Currently supported map formats are:
- Open Street Maps
Installation
pip install mappymatch
If you have trouble with that, check out the docs for more detailed install instructions.
Example Usage
The current primary workflow is to use osmnx to download a road network and match it using the LCSSMatcher.
The LCSSMatcher implements the map matching algorithm described in this paper:
usage:
from mappymatch import package_root
from mappymatch.constructs.geofence import Geofence
from mappymatch.constructs.trace import Trace
from mappymatch.maps.nx.nx_map import NxMap
from mappymatch.matchers.lcss.lcss import LCSSMatcher
trace = Trace.from_csv(package_root() / "resources/traces/sample_trace_1.csv")
# generate a geofence polygon that surrounds the trace; units are in meters;
# this is used to query OSM for a small map that we can match to
geofence = Geofence.from_trace(trace, padding=1e3)
# uses osmnx to pull a networkx map from the OSM database
nx_map = NxMap.from_geofence(geofence)
matcher = LCSSMatcher(nx_map)
matches = matcher.match_trace(trace)
# convert the matches to a dataframe
df = matches.matches_to_dataframe()
Example Notebooks
Check out the LCSS Example for a more detailed example of working with the LCSSMatcher.
2 maintainers
Metadata
2 maintainers
Release files for mappymatch 0.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| mappymatch-0.7.1.tar.gz | 86.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mappymatch-0.7.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 145.0 kB
Release files / mappymatch-0.7.1.tar.gz
| Download URL | mappymatch-0.7.1.tar.gz |
|---|---|
| Size | 86.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
00fdbd24bfb3e37e31983b0933bd7021c0ec69d0f9e2b059d87644baadeb1acf
|
|
BLAKE2b-256 checksum How to use checksums |
5d29489810a24e57dcab3f54645ca88b850d1093070e4de04113c80a5d494964
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 19, 2025.
Transparency logRelease files / mappymatch-0.7.1-py3-none-any.whl
| Download URL | mappymatch-0.7.1-py3-none-any.whl |
|---|---|
| Size | 58.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9f3ca2f88c9eadee41225fc31fba28c1c481018b9266fe1d0b856fecc5be7fdf
|
|
BLAKE2b-256 checksum How to use checksums |
2aaa7cb7a8e641730a4f003ee93df07821e49ec7c792c3351f3d359515358b22
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 19, 2025.
Transparency logSecurity for mappymatch 0.7.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for mappymatch-0.7.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 19, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
