Gods-Eye-View Database Requirements: External Data Feeds and API Credentials Explained

Gods-Eye-View requires no local database installation—it relies entirely on external data feeds including OpenStreetMap-derived datasets, OpenSky API credentials, and Cesium ion tokens, configured via environment variables.

This open-source geospatial visualization application by bilawalsidhu/gods-eye-view fetches all data from third-party APIs and public datasets rather than maintaining internal storage. Understanding these database requirements ensures proper authentication, legal compliance, and full functionality.

---

OpenStreetMap-Derived Data (ODbL Licensed)

The application renders maps using OpenStreetMap-derived geographic datasets distributed under the Open Database License (ODbL). These layers power features like military installation proximity alerts and contextual map overlays.

Key implementation details from the source code:

• The /api/military-installations endpoint queries OSM-derived layers for rendering and analytics
• Attribution is mandatory: all visualizations must display "© OpenStreetMap contributors"
• Redistribution of modified datasets requires maintaining ODbL licensing

As documented in [DATA_SOURCES.md](https://github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md#the-osm‑derived‑datasets‑are-under-the-open-database-license), the application code itself is MIT-licensed, creating a clean separation from the data licensing.

---

OpenSky API Authentication (Required)

Live aircraft tracking requires valid OpenSky Network credentials. The application performs strict authentication validation before issuing any requests.

Required Environment Variables

Variable	Purpose
OPENSKY_USERNAME	Basic authentication username
OPENSKY_PASSWORD	Basic authentication password
OPENSKY_CLIENT_ID	OAuth client identifier
OPENSKY_CLIENT_SECRET	OAuth client secret

The validation logic in vite.config.js (lines 3189-3216) aborts startup with explicit error messages if these variables are missing:

// vite.config.js - authentication validation excerpt
if (!process.env.OPENSKY_CLIENT_ID || !process.env.OPENSKY_CLIENT_SECRET) {
  throw new Error('OpenSky auth missing: OPENSKY_CLIENT_ID and OPENSKY_CLIENT_SECRET required.');
}

Server-side request handlers enforce this at runtime too. From src/data/aisLiveVessels.js:

// src/data/aisLiveVessels.js - runtime auth check
export async function fetchLiveVessels(req, res) {
  const auth = req.headers.get('authorization');
  if (!auth) {
    res.end(JSON.stringify({ error: 'OpenSky auth required.' }));
    return;
  }
  // Bounding box parameters for spatial queries
  const south = requiredFiniteQueryNumber(req.query, 'south');
  const west  = requiredFiniteQueryNumber(req.query, 'west');
  const north = requiredFiniteQueryNumber(req.query, 'north');
  const east  = requiredFiniteQueryNumber(req.query, 'east');
  // ...
}

---

Cesium ion Token (Required for Satellite Layers)

Satellite imagery, terrain elevation, and 3D tiles require a valid Cesium ion access token. The UI actively blocks these features without authentication.

In [src/ui.js](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js#L7958), the application checks for the token before enabling Cesium-hosted layers:

// src/ui.js - token validation before layer activation
if (!cesiumIonToken) {
  showNotification('Cesium ion token required for satellite imagery');
  disableLayer('satellite');
}

Set this in your environment:

CESIUM_ION_TOKEN=your_cesium_ion_token_here

---

Environment Configuration Setup

All database requirements consolidate into a single .env file. Copy from the provided template and populate with your credentials:

# .env.example → .env

cp .env.example .env

Complete configuration:

# OpenSky Network credentials

OPENSKY_USERNAME=your_opensky_username
OPENSKY_PASSWORD=your_opensky_password
OPENSKY_CLIENT_ID=your_opensky_client_id
OPENSKY_CLIENT_SECRET=your_opensky_client_secret

# Cesium ion access token

CESIUM_ION_TOKEN=your_cesium_ion_token

# Additional provider credentials as needed

The startup sequence validates presence and format of these variables before accepting connections.

---

Map Provider Attribution Requirements

Legal compliance extends beyond authentication. [style.css](https://github.com/bilawalsidhu/gods-eye-view/blob/main/style.css#L303) enforces visible attribution for Google Maps Platform, Bing, Esri, and other basemap providers:

/* style.css - mandatory attribution display */
.map-attribution {
  position: fixed;
  bottom: 0;
  right: 0;
  /* Google Maps Platform ToS and Cesium's terms require the credit whenever tiles are visible */
  z-index: 1000;
  pointer-events: none;
}

Removing or obscuring this element violates terms of service.

---

Licensing Compliance Summary

Data Source	License	Key Obligation
OpenStreetMap-derived datasets	ODbL	Attribution + share-alike for redistributions
OpenSky API	Commercial ToS	Rate limits, proper authentication
Cesium ion	Service ToS	Token-based access, display attribution

The application architecture cleanly separates MIT-licensed code from externally-licensed data, simplifying compliance.

---

Summary

• No local database installation—Gods-Eye-View is entirely feed-driven
• Three credential types required: OpenSky (flight data), Cesium ion (imagery), OSM attribution (map data)
• Environment-based configuration via .env file with validation at startup
• Legal compliance enforced through code: authentication checks in vite.config.js, UI guards in src/ui.js, and CSS-mandated attribution

---

Frequently Asked Questions

Does Gods-Eye-View require PostgreSQL, MongoDB, or any local database?

No. According to the bilawalsidhu/gods-eye-view source code, the application has no embedded database. All data flows from external APIs (OpenSky, Cesium ion) and public datasets (OpenStreetMap derivatives). Configuration happens entirely through environment variables.

What happens if I don't provide OpenSky credentials?

The application will fail to start with a clear error message from vite.config.js, and any runtime requests to flight data endpoints will return {"error": "OpenSky auth required."}. Live aircraft tracking will be completely non-functional.

Can I use Gods-Eye-View without a Cesium ion token?

Partially. The base map and OSM-derived layers will function, but satellite imagery, terrain elevation, and 3D tile layers will be disabled. The UI explicitly blocks these features and shows a notification when the token is absent.

What are the legal risks of using OSM-derived data incorrectly?

The ODbL requires attribution and share-alike terms for redistributed derivatives. The application handles attribution automatically via style.css, but if you modify and republish the datasets themselves, you must maintain ODbL licensing. The code/data license separation in DATA_SOURCES.md helps clarify your obligations.

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