HTTP Client

OSRM_HTTP provides the same routing interface as the native OSRM class but connects to a remote osrm-routed server over HTTP. Useful for cloud deployments, shared infrastructure, or when you want to avoid managing local .osrm files.

OSRM_HTTP(base_url='http://localhost:5000', profile='driving', timeout=30.0, session=None, pool_connections=16, pool_maxsize=16)

HTTP client for OSRM that mimics the native OSRM interface.

This allows using a remote OSRM server (osrm-routed) instead of loading data locally. Useful for cloud deployments, shared infrastructure, or when you don't want to manage local .osrm files.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL of the OSRM server (e.g., "http://localhost:5000" or "http://router.project-osrm.org")	'http://localhost:5000'
profile	str	Routing profile to use (default: "driving"). Common options are "driving", "car", "bike", "foot", "walking"	'driving'
timeout	float	Request timeout in seconds (default: 30)	30.0
session	Optional[Any]	Optional requests.Session object for connection pooling	None

Examples:

>>> import osrm
>>> 
>>> # Connect to local OSRM server
>>> client = osrm.OSRM_HTTP("http://localhost:5000")
>>> 
>>> # Or use the public demo instance
>>> client = osrm.OSRM_HTTP("http://router.project-osrm.org")
>>> 
>>> # Same API as native OSRM
>>> result = client.Route([(7.41337, 43.72956), (7.41546, 43.73077)])
>>> print(result["routes"][0]["distance"])
>>> 
>>> # Works with bulk processing
>>> import polars as pl
>>> df = pl.DataFrame({
...     "origin_lon": [7.41337, 7.41862],
...     "origin_lat": [43.72956, 43.73216],
...     "dest_lon": [7.41546, 7.42000],
...     "dest_lat": [43.73077, 43.73300]
... })
>>> results = osrm.bulk_route(client, df)

Source code in osrm/http_client.py

def __init__(
    self,
    base_url: str = "http://localhost:5000",
    profile: str = "driving",
    timeout: float = 30.0,
    session: Optional[Any] = None,
    pool_connections: int = 16,
    pool_maxsize: int = 16,
):
    import requests
    from requests.adapters import HTTPAdapter
    self._requests = requests

    self.base_url = base_url.rstrip('/')
    self.profile = profile
    self.timeout = timeout

    if session is not None:
        self.session = session
    else:
        self.session = requests.Session()
        # Increase connection pool for concurrent bulk_route usage
        adapter = HTTPAdapter(
            pool_connections=pool_connections,
            pool_maxsize=pool_maxsize,
        )
        self.session.mount('http://', adapter)
        self.session.mount('https://', adapter)

    # Verify server is accessible
    try:
        response = self.session.get(f"{self.base_url}/", timeout=5)
        response.raise_for_status()
    except Exception as e:
        raise ConnectionError(
            f"Failed to connect to OSRM server at {self.base_url}: {e}"
        )

Route(coordinates=None, **kwargs)

Calculate route between coordinates.

See OSRM API documentation: http://project-osrm.org/docs/v5.24.0/api/#route-service

Parameters:

Name	Type	Description	Default
coordinates	Optional[List[tuple]]	List of (lon, lat) tuples	None
steps		Return route steps (default: False)	required
alternatives		Search for alternative routes (default: False)	required
geometries		Geometry format: 'polyline', 'polyline6', 'geojson'	required
overview		Overview detail: 'simplified', 'full', 'false'	required
continue_straight		Force straight at waypoints	required
annotations		Annotation types (list or string)	required

Returns:

Type	Description
Dict[str, Any]	Route result as dict

Source code in osrm/http_client.py

def Route(self, coordinates: Optional[List[tuple]] = None, **kwargs) -> Dict[str, Any]:
    """
    Calculate route between coordinates.

    See OSRM API documentation: http://project-osrm.org/docs/v5.24.0/api/#route-service

    Args:
        coordinates: List of (lon, lat) tuples
        steps: Return route steps (default: False)
        alternatives: Search for alternative routes (default: False)
        geometries: Geometry format: 'polyline', 'polyline6', 'geojson'
        overview: Overview detail: 'simplified', 'full', 'false'
        continue_straight: Force straight at waypoints
        annotations: Annotation types (list or string)
        Other OSRM route parameters...

    Returns:
        Route result as dict
    """
    if coordinates is None:
        raise ValueError("coordinates parameter is required")
    if len(coordinates) < 2:
        raise ValueError("At least 2 coordinates are required for routing")

    return self._make_request('route', coordinates, **kwargs)

Table(coordinates=None, **kwargs)

Compute distance/duration table between coordinates.

Parameters:

Name	Type	Description	Default
coordinates	Optional[List[tuple]]	List of (lon, lat) tuples	None
sources		Indices of source coordinates	required
destinations		Indices of destination coordinates	required
annotations		'duration', 'distance', or both	required

Returns:

Type	Description
Dict[str, Any]	Table result as dict

Source code in osrm/http_client.py

def Table(self, coordinates: Optional[List[tuple]] = None, **kwargs) -> Dict[str, Any]:
    """
    Compute distance/duration table between coordinates.

    Args:
        coordinates: List of (lon, lat) tuples
        sources: Indices of source coordinates
        destinations: Indices of destination coordinates
        annotations: 'duration', 'distance', or both
        Other OSRM table parameters...

    Returns:
        Table result as dict
    """
    if coordinates is None:
        raise ValueError("coordinates parameter is required")

    return self._make_request('table', coordinates, **kwargs)

Nearest(coordinates=None, **kwargs)

Find nearest road segment to coordinates.

Parameters:

Name	Type	Description	Default
coordinates	Optional[List[tuple]]	List of (lon, lat) tuples (typically just one)	None
number		Number of nearest segments to return (default: 1)	required

Returns:

Type	Description
Dict[str, Any]	Nearest result as dict

Source code in osrm/http_client.py

def Nearest(self, coordinates: Optional[List[tuple]] = None, **kwargs) -> Dict[str, Any]:
    """
    Find nearest road segment to coordinates.

    Args:
        coordinates: List of (lon, lat) tuples (typically just one)
        number: Number of nearest segments to return (default: 1)
        Other OSRM nearest parameters...

    Returns:
        Nearest result as dict
    """
    if coordinates is None:
        raise ValueError("coordinates parameter is required")

    return self._make_request('nearest', coordinates, **kwargs)

Match(coordinates=None, **kwargs)

Match GPS trace to road network.

Parameters:

Name	Type	Description	Default
coordinates	Optional[List[tuple]]	List of (lon, lat) tuples for GPS trace	None
timestamps		Timestamps for each coordinate	required
steps		Return route steps	required
geometries		Geometry format	required
overview		Overview detail	required
annotations		Annotation types	required
gaps		Gap handling: 'split' or 'ignore'	required
tidy		Clean up trace	required

Returns:

Type	Description
Dict[str, Any]	Match result as dict

Source code in osrm/http_client.py

def Match(self, coordinates: Optional[List[tuple]] = None, **kwargs) -> Dict[str, Any]:
    """
    Match GPS trace to road network.

    Args:
        coordinates: List of (lon, lat) tuples for GPS trace
        timestamps: Timestamps for each coordinate
        steps: Return route steps
        geometries: Geometry format
        overview: Overview detail
        annotations: Annotation types
        gaps: Gap handling: 'split' or 'ignore'
        tidy: Clean up trace
        Other OSRM match parameters...

    Returns:
        Match result as dict
    """
    if coordinates is None:
        raise ValueError("coordinates parameter is required")
    if len(coordinates) < 2:
        raise ValueError("At least 2 coordinates are required for matching")

    return self._make_request('match', coordinates, **kwargs)

Trip(coordinates=None, **kwargs)

Solve traveling salesman problem.

Parameters:

Name	Type	Description	Default
coordinates	Optional[List[tuple]]	List of (lon, lat) tuples	None
roundtrip		Return to start point (default: True)	required
source		Source constraint: 'any' or 'first'	required
destination		Destination constraint: 'any' or 'last'	required
steps		Return route steps	required
geometries		Geometry format	required
overview		Overview detail	required
annotations		Annotation types	required

Returns:

Type	Description
Dict[str, Any]	Trip result as dict

Source code in osrm/http_client.py

def Trip(self, coordinates: Optional[List[tuple]] = None, **kwargs) -> Dict[str, Any]:
    """
    Solve traveling salesman problem.

    Args:
        coordinates: List of (lon, lat) tuples
        roundtrip: Return to start point (default: True)
        source: Source constraint: 'any' or 'first'
        destination: Destination constraint: 'any' or 'last'
        steps: Return route steps
        geometries: Geometry format
        overview: Overview detail
        annotations: Annotation types
        Other OSRM trip parameters...

    Returns:
        Trip result as dict
    """
    if coordinates is None:
        raise ValueError("coordinates parameter is required")
    if len(coordinates) < 2:
        raise ValueError("At least 2 coordinates are required for trip")

    return self._make_request('trip', coordinates, **kwargs)

Tile(x, y, z)

Get vector tile data.

Parameters:

Name	Type	Description	Default
x	int	Tile X coordinate	required
y	int	Tile Y coordinate	required
z	int	Tile zoom level	required

Returns:

Type	Description
bytes	Tile data as bytes

Source code in osrm/http_client.py

def Tile(self, x: int, y: int, z: int) -> bytes:
    """
    Get vector tile data.

    Args:
        x: Tile X coordinate
        y: Tile Y coordinate
        z: Tile zoom level

    Returns:
        Tile data as bytes
    """
    url = f"{self.base_url}/tile/v1/{self.profile}/tile({x},{y},{z}).mvt"

    try:
        response = self.session.get(url, timeout=self.timeout)
        response.raise_for_status()
        return response.content
    except self._requests.exceptions.RequestException as e:
        raise RuntimeError(f"Failed to fetch tile: {e}")