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

> Discover God's Eye View basemap fallback options. Learn how the three-tier map stack ensures seamless rendering from Esri to OpenStreetMap, even without API keys.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: architecture
- Published: 2026-09-09

---

**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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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

```javascript
// 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

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md) lines 83-90**: Describes the three-tier credential system and what each tier provides
- **[`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md) lines 2205-2209**: Summarizes the fallback behavior and default stack selections
- **[`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md) lines 83-90.