Beyond Simple Map APIs: How Spatial‑Agent Enables LLMs to Build Executable Geo‑Analysis Workflows

Why Map QA is not the same as geospatial analysis

Single‑step map APIs can answer factual questions such as retrieving a place’s address or computing a route, but many real‑world spatial queries require multi‑step reasoning. For example, calculating the proportion of restaurants in a region that satisfy distance, rating, opening‑hours, and routing constraints depends on the order of operations (filtering → aggregation → measurement). A naïve LLM may generate plausible yet incorrect workflows because the operation order dramatically changes the result.

Spatial‑Agent: Turning natural language into a GeoFlow Graph

Spatial‑Agent inserts a GeoFlow Graph between the user’s question and tool calls. Nodes represent spatial concepts (Location, Object, Event, Network, Amount, etc.) and edges encode transformation relationships. The agent first extracts concepts and assigns functional roles (Extent, Condition, Measure, etc.), then selects from a library of validated macro‑templates (e.g., “filter‑aggregate‑measure”, “object‑to‑distance field”, “routing optimization”). These templates guide the construction of a dependency‑aware graph that respects operation order, type compatibility, data availability, and connectivity before mapping each edge to concrete tools such as geocoding, place search, routing, distance matrix, spatial filtering, or trip optimization.

Theoretical foundations from GIScience

The approach builds on two strands of GIScience literature. The first defines core concepts of spatial information (Location, Field, Object, Network, Event) as described by Goodchild (1992) and Kuhn (2012). The second treats these concepts as functional roles within analysis workflows, following Scheider et al. (2020) and Xu et al. (2023), which distinguish between concepts that serve as inputs, conditions, or final measures. Spatial‑Agent identifies these concepts in the query and tags their roles, enabling a systematic translation into a GeoFlow Graph.

Method: From concept extraction to tool execution

The pipeline consists of four stages:

Concept and role extraction from the natural‑language query.

Template retrieval: a set of pre‑validated macro‑templates that capture common GIS patterns.

Graph construction: assembling a GeoFlow Graph that satisfies ordering, type, and data constraints.

Tool mapping and execution: each graph edge is realized by calling appropriate APIs (geocoding, place search, routing, distance matrix, spatial filtering, trip optimization) while recording intermediate states for later verification.

This design allows the system to check which concepts were recognized, which conditions were processed first, and which intermediate results the final answer depends on.

Experiments: Workflow constraints yield more stable agent performance

Spatial‑Agent was evaluated on two benchmarks:

MapEval‑API (Place Info, Nearby, Routing, Trip) covering 54 countries and 180 cities.

MapQA, an open‑domain geospatial QA set derived from OpenStreetMap.

Key results (accuracy percentages):

MapEval‑API with Spatial‑Agent + GPT‑4o‑mini: 45.15 % vs. baseline 23.00 % (≈96 % relative improvement).

MapEval‑API with Spatial‑Agent + GPT‑5: overall 71.88 %, Routing 75.76 %, Trip 77.61 %.

MapQA with GPT‑4o‑mini / LLaMA‑70B / Qwen2.5‑72B‑Instruct: 61.45 % / 62.45 % / 61.45 % respectively.

Ablation (Spatial‑Agent without templates) on MapEval‑API: 45.15 % vs. 39.32 % without templates.

Error analysis shows most failures occur in the execution layer (e.g., ambiguous place names, missing POI data, incomplete routing information), indicating that once the workflow is correct, data quality becomes the bottleneck.

Conclusion and limitations

Spatial‑Agent demonstrates that in domains with mature theoretical foundations and tool ecosystems, merely chaining LLM thoughts to APIs is insufficient. By grounding reasoning in GIScience core concepts and functional roles, and by generating a verifiable GeoFlow Graph before tool invocation, agents achieve more reliable geospatial reasoning. Limitations include dependence on external API data quality, incomplete template coverage, and the need for manual annotation of fine‑grained concepts. Future work should expand language support, cover more specialized geographic tasks, and integrate richer spatial analysis toolchains.

Code repository: https://github.com/ecerybao/Spatial-Agent