Research across the humanities, social sciences, and data science frequently deals with events that are embedded in both space and time. A historical conflict has coordinates and a date. A GPS track records movement through a city over an afternoon. An archival document references places and periods that need to be resolved, indexed, and queried.
Yet working with this kind of data often means stitching together separate tools for spatial indexing, temporal filtering, text processing, and format conversion. Spatial Narrative was developed to bring these capabilities together in a single, performant Rust library.
What Is Spatial Narrative?
Spatial Narrative is a Rust crate for creating, indexing, and analysing events with geographic coordinates, multi-precision timestamps, metadata, and semantic tags. It is designed for researchers, digital humanists, and data scientists who work at the intersection of space, time, and text.
The library is available on crates.io and can be installed with:
cargo add spatial-narrativeOr with the full feature set (including ML-powered named entity recognition):
cargo add spatial-narrative -F fullCore Capabilities
The library is organised into eight modules, each addressing a different aspect of spatiotemporal analysis.
Flexible Event Representation
At the heart of the library is the Event type. Events carry WGS84 coordinates, timestamps with variable precision (from year-level to second-level granularity), extensible metadata, and semantic tags. Events are grouped into Narrative collections for batch analysis.
This flexibility is important: historical datasets rarely have precise timestamps, and being able to represent “sometime in 1943” alongside “14:32:07 on 3 February 2025” without losing either is essential for cross-temporal research.
Spatial Indexing
Spatial Narrative provides R*-tree and quadtree indexing structures for efficient spatial queries. Nearest neighbour search, bounding box operations, and range queries all operate with logarithmic complexity. This matters when working with thousands or millions of events—queries that would be linear scans become near-instant lookups.
Heatmap generation is also supported directly from the spatial index, useful for visualising event density across a study area.
Text Processing and Named Entity Recognition
One of the more distinctive features is the built-in text processing pipeline. The library includes both pattern-based and ML-powered named entity recognition. The ML pathway uses BERT models via ONNX Runtime, achieving F1 scores between 90% and 93% depending on the model. This allows researchers to extract place names, organisations, and other entities directly from narrative text without leaving the Rust ecosystem.
Movement Analysis
For trajectory data (GPS tracks, migration paths, delivery routes), the library provides trajectory simplification, speed calculation, stop detection, and clustering algorithms (DBSCAN and k-means). These tools support research into urban mobility, logistics optimisation, and activity pattern recognition.
Multi-Format I/O
Data rarely lives in a single format. Spatial Narrative supports import and export across JSON, GeoJSON, CSV, GPX tracks, and SQLite (with full-text search). This makes it straightforward to ingest data from field collection tools, export to GIS platforms, or persist indexed collections in a local database.
Use Cases
The library was designed to support a range of disciplines:
- Digital humanities — indexing historical events, literary geography, archival analysis
- Social science — migration patterns, urban mobility, conflict studies
- Journalism — investigative geospatial research, fact-checking, data-driven stories
- Logistics — GPS track analysis, route optimisation, delivery pattern recognition
- Personal projects — photo organisation by location and time, travel diaries, family history
Performance and Testing
The library currently passes 199 unit tests across all modules. Core spatial operations (haversine distance, R*-tree queries, DBSCAN clustering) are benchmarked and operate within expected algorithmic complexity bounds.
Being written in Rust, the library benefits from zero-cost abstractions, memory safety without garbage collection, and straightforward deployment as a compiled binary or library dependency.
Documentation and Source Code
Full documentation is available:
- Project homepage — overview, features, and quick start
- API reference — complete type and function documentation
- User guide — tutorials and worked examples
- GitHub repository — source code, issues, and contributions
The project is MIT licensed and open to contributions.
Looking Forward
Spatial Narrative is part of a broader effort to build research tools that respect the complexity of place-based data. Where traditional GIS treats locations as abstract coordinates, this library is designed to support the richer, messier reality of events that carry meaning, context, and narrative alongside their geometry.
If you work with spatiotemporal data in any discipline, I would welcome feedback, feature requests, or contributions via the GitHub repository.
