GeoSpark

GeoSpark Verifiable spatial reasoning for large language models. Distances, topology, coordinate reference systems and heights computed by a geometry engine and official geodetic models, not estimated by a language model. Open source, self-hostable, and usable by any model that can call a tool.

---

GeoSpark provides language models with tools that compute spatial answers rather than estimate them: geodesic distances, exact topology, official datum and height conversions, geocoding, elevation, routing, open map data and live environmental data. Each result carries its sources, licences, units and caveats, and a result that cannot be computed reliably is reported as such rather than approximated. GeoSpark also checks users' own datasets (vector files, LiDAR point clouds and elevation models) for the silent coordinate and height errors that most often corrupt spatial analyses.

Contents: Motivation and evaluation history · Capabilities · Access and installation · Usage · Command-line interface · Evaluation · Validation against authoritative sources · Limitations · Self-hosting · Release history · Data attribution · Development · Citation

Motivation and evaluation history

GeoSpark is evaluated against the models in current use, and its scope follows the gaps that those evaluations reveal.

• GeoSpark Bench v2. Across nine models of the time, small open-weight models (3.8B–9B parameters) answered numeric distance questions incorrectly about 95% of the time, and frontier APIs ranged from 25% to 95% correct. With GeoSpark's tools, every model that issued valid tool calls answered 76–96% correctly; a 7B model running on a CPU improved from 5% to 76%.
• Re-evaluation with current models (October 2026). Claude Opus 5.5 and GPT-6.1 now answer the same distance and topology questions correctly without tools, and with GeoSpark's tools a 4B open model on a workstation matches them. Distances between given points are no longer the limiting problem.
• Identification of the next gap. Both frontier models apply datum parameters, plate motion and map projections to the millimetre, but fail on conversions that require a national grid file: ellipsoidal (GNSS) heights to AHD, ODN, NZVD2016 or NAVD88, and British National Grid through OSTN15. Answering directly, including within the providers' own code sandboxes (which have no internet access), GPT-6.1 declined and Opus 5.5 estimated, with errors of up to 9.9 m. GeoSpark now performs these conversions with the official grids. When asked instead to write a script executed with internet access, both frontier models produced correct results; smaller local models did not.
• Independent verification. Agreement with PROJ demonstrates only that a model used the tool correctly. GeoSpark's own results were therefore compared with the published calculators and test data of Geoscience Australia, Ordnance Survey, LINZ and the US National Geodetic Survey, agreeing within millimetres with one disclosed exception. The same audit corrected statements in the project's documentation and fixed the edge cases it exposed.
• Small-model safety. Four open models on a local workstation were run through GeoSpark's question-answering loop to measure how often an incorrect answer is still reported as ok. Each failure mode found (unsupported numbers, empty answers, contradictory comparisons, an ambiguous place name resolved to the wrong country) is now detected; after the changes, 120 answers over three runs contained one silent error, which has since been fixed.

All questions, answer-generation scripts, harnesses and scored results are included in the repository and can be re-run (evaluation, October 2026 materials).

Current state of the project

• A public website, REST API and hosted MCP server at geospark.terrascout.app, offering question answering, reachable-area (isochrone) mapping, open map data exploration, and datum and height conversion.
• Verifiable results: sources and licences, units, caveats (an ambiguous place name, a DEM's accuracy, a local height datum) and a status of ok, partial or cannot_answer. An answer that relies on coordinates typed by the model, converts to a different system than the question specifies, or states quantities that no tool returned is marked partial.
• Dataset checks for vector files, LiDAR point clouds and elevation models: declared and actual coordinate reference systems, datum mix-ups, wrong zones, units, and height references.
• Self-hostable on a single server with a local model at no API cost: routing (Valhalla), an OpenStreetMap replica (Overpass) and the official geodetic grids, all under one data directory.
• Open: Apache-2.0 licence, about 1,250 offline tests, and re-runnable benchmarks.

Capabilities

Access and installation

Website. geospark.terrascout.app provides question answering, reachable-area mapping and Overture Maps exploration around any location. Every result shows its sources, caveats and units, and can be downloaded as GeoJSON.

Hosted REST API (open, no key required; API reference):

curl -X POST https://geospark.terrascout.app/api/v1/distance \

-H "Content-Type: application/json" \ -d '{"lat_a": 48.8584, "lon_a": 2.2945, "lat_b": 48.8606, "lon_b": 2.3376}'

{"distance_m": 3172.01, "distance_km": 3.172, "note": "Geodesic distance on WGS84 ellipsoid"}

Hosted MCP server. In Claude or any MCP client, add a custom connector with the following URL (in Claude: Settings → Connectors → Add custom connector):

https://geospark.terrascout.app/mcp

The hosted server is open, requires no key, offers 21 tools and applies the same rate limits as the hosted API. It does not read files; tools for local files are available only from a locally run server.

Local MCP server (Claude Desktop or any MCP client):

pip install "geospark-ai[mcp]"

Register the server in the MCP client's configuration. For Claude Desktop, the file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows:

{ "mcpServers": { "geospark": { "command": "geospark-mcp" } } }

The local server provides 25 read-only tools:

• Computation: calculate_distance (between place names, geocoded by the server, or coordinates), check_spatial_relationship, spatial_operation (buffer, area, length, centroid, convex hull), transform_coordinates and convert_height.
• Places and data: geocode, reverse_geocode, get_elevation, route, get_weather, get_air_quality, get_active_fires and overture_features.
• Sun and terrain: sun_position, sun_times, terrain_horizon and line_of_sight.
• Analysis: isochrone, travel_time_matrix, location_report and select_site.
• Local files (local server only): check_dataset, layer_info, layer_count_within and layer_nearest.

Results are returned as structured content with output schemas, usually GeoJSON, and carry provenance (source, licence, attribution), units and warnings. When a result cannot be computed reliably (invalid geometry, an unknown place, an unavailable data source), the tool returns an error stating the reason, so that the model can report it instead of estimating. The server uses MCP SDK 2.x (protocol 2026-07-28) and remains compatible with clients on earlier protocol versions.

Python library:

pip install geospark-ai                  # core

pip install "geospark-ai[api,mcp]" # REST server and MCP server pi