Basemap Fallback Options in God's Eye View: The Three-Tier Map Stack System

God's Eye View implements a three-tier basemap ladder that automatically falls back from Esri World Imagery to OpenStreetMap tiles when satellite imagery fails to load, ensuring the globe never renders blank even when no API keys are configured.

The open-source bilawalsidhu/gods-eye-view repository provides a robust mapping interface that gracefully degrades between data sources based on available credentials. Understanding the basemap fallback options in God's Eye View helps developers predict application behavior across different deployment scenarios and network conditions. The system prioritizes high-fidelity 3D imagery when API keys are present while maintaining functional fallbacks for key-less deployments.

The Basemap Ladder Architecture

The application uses a tiered system defined in src/mapStackController.js (lines 19-56) that determines which map source renders and how the system behaves when higher-tier sources are unavailable.

Tier 1: Key-less Operation with Esri and OSM Fallback

When no API credentials are supplied, the system defaults to Esri World Imagery satellite basemap with key-less 2D terrain. If Esri tiles fail to fetch due to network errors or service outages, the controller automatically falls back to OSM (OpenStreetMap) tiles according to the implementation in src/mapStackController.js lines 53-64.

Tier 2: Cesium Ion Token for Google 3D

With a free Cesium ion token, the app renders Google Photorealistic 3D cities with world terrain enabled. This tier has no fallback mechanism—the system attempts to load the ion-hosted Google 3D tiles directly without secondary options.

Tier 3: Google Maps API Key

When a metered Google Maps key is provided, the app displays the same Google Photorealistic 3D tiles plus activates in-app place search functionality. Like Tier 2, this configuration offers no fallback and relies exclusively on Google's key-protected tile services.

How the Automatic Fallback Mechanism Works

The fallback logic resides in src/mapStackController.js between lines 53-64. When the active stack is set to Esri Imagery (esri-imagery) and tile requests return errors, the controller immediately swaps to the OSM stack (osm) and updates the state with a descriptive error message.

This ensures users never encounter a blank globe. The default stack selection logic prioritizes photoreal when either a Google key or ion token exists; otherwise, it initializes with esri-imagery and the OSM safety net.

Programmatic Control of Basemap Stacks

Developers can manually control basemap switching and inspect fallback states using the mapStackController API.

Switching Basemaps Programmatically

// Activate Google 3D (requires ion token or Google key)
await mapStackController.setStack('photoreal');

// Activate Esri satellite (key-less, with automatic OSM fallback)
await mapStackController.setStack('esri-imagery');

Monitoring Fallback Status

// Inspect the current state (includes any fallback message)
const state = mapStackController.getState();
console.log(state.activeId);   // Returns "osm" if Esri failed
console.log(state.lastError);  // "Esri Satellite is unavailable; using OSM"

Configuration Files and Documentation

The basemap ladder behavior is documented across multiple project files:

• README.md lines 83-90: Describes the three-tier credential system and what each tier provides
• docs/CURRENT-STATE.md lines 2205-2209: Summarizes the fallback behavior and default stack selections
• src/mapStackController.js: Contains the actual implementation of stack definitions, default selection logic, and the Esri-to-OSM fallback handling

Summary

• The basemap ladder determines map sources based on three credential tiers: none (Esri/OSM), Cesium ion token (Google 3D), or Google Maps key (Google 3D + search)
• Esri World Imagery automatically falls back to OSM tiles when unavailable, ensuring continuous functionality
• Google Photorealistic 3D requires valid credentials and provides no fallback mechanism
• Use mapStackController.setStack() to programmatically switch between photoreal, esri-imagery, and osm stacks
• Inspect mapStackController.getState() to detect active fallbacks via the activeId and lastError properties

Frequently Asked Questions

What happens when Esri World Imagery fails to load in God's Eye View?

The application automatically falls back to OpenStreetMap (OSM) tiles. This behavior is hardcoded in src/mapStackController.js lines 53-64, which catches tile loading errors and swaps the active stack to osm while logging the failure in the state object's lastError property.

Does the Google Photorealistic 3D basemap have a fallback option?

No. According to the source code in src/mapStackController.js, the photoreal stack (Google Photorealistic 3D) requires either a Cesium ion token or Google Maps API key. When these credentials are present, the system attempts to load the 3D tiles directly without implementing a secondary fallback mechanism.

How do I check if the basemap has fallen back to OSM programmatically?

Call mapStackController.getState() and examine the activeId property. If Esri Satellite was unavailable, this value will be "osm" instead of "esri-imagery". The lastError string will also contain a descriptive message explaining that Esri Satellite is unavailable and OSM is being used.

What is the default basemap when no API keys are configured?

Without any API keys, the application defaults to the Esri World Imagery stack (esri-imagery) with automatic fallback to OSM. This key-less configuration provides 2D satellite imagery and ensures the globe remains visible even during service interruptions, as documented in README.md lines 83-90.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}