Spatial Narrative

Extract geographic narratives from text.

What It Does

spatial-narrative extracts locations and events from unstructured text, turning documents into structured geospatial data.

Input:  "The summit in Paris brought together leaders from Berlin and Tokyo.
         Negotiations continued through the week before concluding in Geneva."

Output: [
  { location: Paris (48.86°, 2.35°), text: "summit" },
  { location: Berlin (52.52°, 13.41°), text: "leaders" },
  { location: Tokyo (35.68°, 139.65°), text: "leaders" },
  { location: Geneva (46.20°, 6.14°), text: "concluding" }
]

Core Workflow

┌──────────────┐      ┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│     Text     │  →   │  Geoparser   │  →   │   Narrative  │  →   │    Export    │
│  (documents, │      │  (extract    │      │   (events,   │      │  (GeoJSON,   │
│   articles)  │      │   locations) │      │   analysis)  │      │   mapping)   │
└──────────────┘      └──────────────┘      └──────────────┘      └──────────────┘

Key Features

Feature	Description
Geoparsing	Extract place names from text and resolve to coordinates
Built-in Gazetteer	2,500+ world cities with coordinates, population, aliases
Coordinate Detection	Parse decimal degrees, DMS, and other coordinate formats
Online Gazetteers	Optional Nominatim, GeoNames, Wikidata integration
Event Modeling	Structure extracted locations into events with timestamps
Analysis	Clustering, spatial metrics, trajectory detection
Export	GeoJSON, CSV, JSON for mapping tools

Quick Example

use spatial_narrative::parser::{GeoParser, BuiltinGazetteer};

// Create parser with built-in gazetteer (2500+ cities, no API needed)
let gazetteer = BuiltinGazetteer::new();
let parser = GeoParser::with_gazetteer(gazetteer);

// Extract locations from text
let text = "Fighting broke out near Kyiv before spreading to Kharkiv and Odesa.";
let mentions = parser.extract(text);

for mention in &mentions {
    if let Some(loc) = &mention.location {
        println!("{}: ({:.2}°, {:.2}°)", mention.text, loc.lat, loc.lon);
    }
}
// Kyiv: (50.45°, 30.52°)
// Kharkiv: (49.99°, 36.23°)
// Odesa: (46.48°, 30.73°)

Use Cases

Journalism: Extract locations from news articles to map story development
Intelligence: Geolocate events from reports and social media
Historical Research: Map events from historical documents
Disaster Response: Extract affected locations from situation reports
Academic Research: Ground qualitative text data in geography

Modules

Module	Purpose
`parser`	Geoparsing: extract locations from text
`core`	Data types: Event, Location, Timestamp, Narrative
`analysis`	Clustering, metrics, trajectory analysis
`index`	Spatial/temporal indexing for large datasets
`graph`	Event relationship networks
`io`	GeoJSON, CSV, JSON export

Getting Started

Ready to extract locations from text? Start with the Installation guide!

Spatial Narrative Documentation