Spatial Service

Overview

The Spatial Service is the platform's geographic intelligence layer — responsible for all operations involving geographical data and mapping the geospatial relationships between entities in the OR stack. It functions as the unified interface to a suite of spatial tools and databases, enabling other services to geo-tag events, resolve locations, label road segments, and query spatial relationships without needing to manage low-level geospatial complexity directly.

From labelling an incident with the suburb it falls in, to determining which road segments are impacted by a traffic event, to encoding geographic regions into hexagonal tiles for efficient viewport queries — the Spatial Service is the single service through which all geospatial reasoning flows. It underpins the platform's ability to turn raw coordinates into meaningful location context that operators and AI agents can act on.

The service also integrates closely with the Location Reference Service (LRS), a platform API that ingests and transforms reference data into the location database. LRS enables point-and-click location referencing on the map — when a user clicks a point, LRS finds all intersecting geo-features (local government areas, postcodes, road names, and up to 20 spatial attributes), calculates the nearest intersection, and returns a rich location description including distance, direction, and locality.

Architecture

The Spatial Service operates as a dedicated geographic intelligence system that provides geospatial capabilities to the OR platform. It integrates multiple spatial capabilities including location databases, road network graphs, geocoding services, and hexagonal tiling.

Key Capabilities

• Location Database Interface — Stores and queries real-time geospatial data, tracking positions, locations, and boundaries of objects. Supports spatial operations like point-in-polygon, proximity search, and geofencing.
• Road Network Graph — Loads the relevant road network graph on startup (version retrieved from the central orchestration service) and exposes graph-level operations for mapping objects to and from the road network.
• Geocoding Service — Converts latitude/longitude coordinates into street addresses for frontend display and human-readable location labelling.
• Hexagonal Tiling API — Implements a hexagonal tiling system for spatial indexing and viewport-based data retrieval. Uses Resolution 6 for storing hex indices in the database.

Data Flow

The central orchestration service provides map version metadata to the Spatial Service. On startup, the Spatial Service loads the road network graph from cloud storage, initializes the location database, and exposes HTTP endpoints for spatial operations. Consumers including Data Loader, Data Ingestion, the Frontend, and the Location Reference Service utilize these spatial capabilities.

Real-Time Geospatial Store

The location database is the backbone of the Spatial Service's real-time geospatial capabilities. It provides an in-memory spatial database optimized for tracking the positions and boundaries of objects, with support for geofencing, proximity queries, and spatial searches.

The LRS module uses dedicated collections to store reference geospatial data — including local government areas, postcodes, declared roads, and other geo-features. These collections are loaded by the LRS Data Loader automated job, which runs on a schedule aligned with Map Manager updates.

Road Network Map Loading

On startup, the Spatial Service loads the current basemap as a road network graph object. The map version is determined by querying the central orchestration service's Map Data API, using the latest map based on the data loader timestamp.

This graph is held in memory and used for:

• Mapping external coordinate data onto road segments
• Geocoding operations (matching input coordinates to the nearest road network elements)
• Providing the spatial backbone for other services that need to resolve coordinates to road IDs

The map can be reloaded at runtime without restarting the service.

Geocoding Interface

The geocoding interface maps coordinate-based route data onto road network segments. The message protocol has two parts:

Input Messages:

Key	Type	Description
route_id	String	Route ID for identifying the result in output (e.g. traffic management location code)
link_ids	Array of integers	Link IDs (not used by the mapping interface directly)
dirs	Array of strings	Direction indicators — F (From: use path as-is) or T (To: reverse coordinates)
coords	Array of coordinate pairs	Lat/lon coordinate pairs defining the path
config	Object	User settings for the mapper (e.g. mapping error metric selection)

Output Messages:

Key	Type	Description
road_ids	Array of integers	Matched road segment IDs
route_id	String	Original route ID echoed back
dirs	Array of strings	Road segment directions
error_value	Float	Error of match based on selected error metric
len	Array of floats	Length of each matched road segment in meters
offsets	Array of floats	Offset of first/last segment IDs against input linestring in meters

Direction convention: F means the coordinates follow the path direction and can be used as-is. T means coordinates are reversed — the list of GPS coordinates needs to be reversed to get the actual direction of intended travel. When flipping a series of segments, the entire link ordering must also be reversed, not just individual segment coordinates.

Offsets: The matched road network linestring typically differs from the submitted path because road segments have fixed lengths. Positive offset values represent the additional distance that the road segment endpoints extend beyond the input linestring endpoints. To get the overlap of the matched first/last segment IDs against the target linestring, subtract the offset value from the segment length.

Hexagonal Tiling

The hexagonal tiling system enables efficient spatial indexing for viewport-based data loading. The service exposes endpoints for encoding and decoding geographic features into hexagonal indices:

Endpoint	Description
/hex/encode_polygon	Encodes a polygon into hexagonal tile IDs
/hex/encode_linestring	Encodes a linestring into hexagonal tile IDs
/hex/encode_point	Encodes a point into hexagonal tile IDs
/hex/decode_viewport	Decodes a viewport bounding box into hexagonal tile IDs

These endpoints power zoom-level-aware data loading in the frontend:

Level	Zoom	Tiles Covering Victoria	Roads Shown
Macro	5	770	Highways and Arterials
Meso	6	5,394	Plus Primary and Secondary
Micro	7	37,826	All (no road filter)

At Zoom 5, each hexagon is approximately 8 km across (approximately 16 km per tile hexagon). Resolution 6 is the standard for storing hexagonal indices in the database schema (columns on the Ways, EnvObj, and Events tables).

Location Reference Service (LRS)

The LRS is a platform API that provides rich location referencing for points and lines on the road network. It ingests reference data from Map Manager exports and map datasets into the location database, then services two primary queries:

• Get Location Reference Data For Geodetic — Given a point or set of points, returns intersecting geo-features (up to 20 spatial attributes including local government area, postcode, locality, road names, emergency service region, and more).
• Get Location Way ID Data — Given a road segment ID, resolves its geometries and finds all intersecting features.

Core LRS capabilities:

• Nearest Point: Finds the nearest road to an off-road point
• Closest Intersection: Finds the nearest intersection to a given point
• Literal Description: Calculates the nearest intersection, queries it for data, and returns distance, direction, locality, and road names
• Snapping: When snapping options are enabled, points snap to the nearest intersection rather than the nearest road. For lines, snapping can be set independently for the first and last coordinates.

LRS data is refreshed through Map Manager automated workflows that run on a bi-monthly schedule (map deltas on the 1st and 15th, transport map deltas on the 9th and 23rd), followed by the LRS Data Loader automated job which loads updated data into the location database.

Related Services

• Experiment Manager — Provides map version metadata and the central orchestration layer
• Route Finder — Uses the same road network graph infrastructure for route calculation
• Map Manager — Manages basemap versions, exports map data consumed by LRS
• Schematics — Uses location database integration for spatial data in schematic views
• Data Ingestion — Sends coordinate data to Spatial for geo-tagging
• Data Loader — Loads reference data that Spatial Service consumes on startup