mappymatch.matchers.osrm

mappymatch.matchers.osrm#

Functions

parse_osrm_json(j, trace)

Parse the JSON response from the OSRM match service into Match objects.

Classes

OsrmMatcher([osrm_address, osrm_profile, ...])

Map matcher that uses an OSRM server for matching GPS traces to OpenStreetMap data.
mappymatch.matchers.osrm.parse_osrm_json(j: dict, trace: Trace) → list[Match][source]#

Parse the JSON response from the OSRM match service into Match objects.

Extracts matching information from the OSRM response and creates Match objects linking GPS coordinates to road segments (represented by OSM node IDs).

Args:

j: The JSON response dictionary from OSRM's match endpoint trace: The original GPS trace that was matched

Returns:

A list of Match objects, one for each coordinate in the trace

Raises:

ValueError: If the response is missing required fields (matchings, legs, annotations, or nodes)

Note:

Currently the geometry and distance information from OSRM is not fully utilized. This is a TODO for future improvement.

class mappymatch.matchers.osrm.OsrmMatcher(osrm_address='http://router.project-osrm.org', osrm_profile='driving', osrm_version='v1')[source]#

Map matcher that uses an OSRM server for matching GPS traces to OpenStreetMap data.

OSRM (Open Source Routing Machine) is a routing engine for OpenStreetMap data. This matcher sends GPS coordinates to an OSRM match endpoint and receives back matched road segments based on OSM node IDs.

The matcher communicates with OSRM's match API, which snaps GPS points to the nearest roads in the OSM network.

Args:

osrm_address: The base URL of the OSRM server. Default is the public OSRM demo server (not recommended for production use). osrm_profile: The routing profile to use ('driving', 'walking', 'cycling', etc.). Default is 'driving'. osrm_version: The OSRM API version. Default is 'v1'.

Attributes:

osrm_api_base: The constructed OSRM API endpoint URL

Examples:
>>> from mappymatch.matchers.osrm import OsrmMatcher
>>>
>>> # Use default public OSRM server (for testing only)
>>> matcher = OsrmMatcher()
>>> result = matcher.match_trace(trace)
>>>
>>> # Use your own OSRM instance
>>> matcher = OsrmMatcher(
...     osrm_address='http://localhost:5000',
...     osrm_profile='cycling'
... )
Note:

  • Traces must be in WGS84 (EPSG:4326) coordinate system

  • Traces are automatically downsampled to 100 points if longer

  • The public demo server is rate-limited; use your own instance for production

match_trace(trace: Trace) → MatchResult[source]#

Match a GPS trace to roads using the OSRM map matching service.

This method sends the trace to an OSRM server for map matching against OpenStreetMap data. The trace must be in EPSG:4326 (lat/lon). If the trace has more than 100 points, it's automatically downsampled to meet OSRM's typical API limits.

Args:

trace: The GPS trace to match. Must be in EPSG:4326 (lat/lon).

Returns:

A MatchResult containing matches for each GPS point. Note that the current implementation has limited geometry/distance information from OSRM.

Raises:

TypeError: If the trace is not in EPSG:4326 requests.HTTPError: If the OSRM server returns an error response

Examples:
>>> matcher = OsrmMatcher()
>>> trace = Trace.from_csv('gps_data.csv', xy=False)  # Keep in lat/lon
>>> result = matcher.match_trace(trace)
>>>
>>> # Long traces are automatically downsampled
>>> long_trace = Trace.from_gpx('long_journey.gpx')  # 500 points
>>> result = matcher.match_trace(long_trace)  # Downsampled to 100 points
Contents