Gods-Eye-View Data Sources: Live APIs and Bundled Static Datasets Explained

God’s-Eye-View supports a hybrid architecture of twenty-plus live runtime APIs—including Google Map Tiles, OpenSky Network, and OpenStreetMap—alongside bundled static datasets like Natural Earth and TeleGeography cables, all unified through a centralized attribution system in src/data/dataCredits.js.

The open-source repository bilawalsidhu/gods-eye-view aggregates global situational awareness data for 3-D globe visualization. Understanding the complete gods-eye-view data sources ecosystem is essential for developers deploying the application in offline environments or customizing data layers for commercial use.

Live Runtime Data Sources

These APIs are queried on-the-fly through server-side proxies and are not stored in the repository. The application handles rate limiting, caches responses (typically 5–15 minutes), and registers attributions automatically via viewer.creditDisplay.addStaticCredit. Each source is accessed through endpoints like /api/flight or /api/terrain/heights.

Aviation and Maritime Tracking

• OpenSky Network: Provides worldwide live-flight snapshots for research and education use. Citation required: Schäfer et al., Bringing Up OpenSky (IPSN 2014).
• adsb.lol point API: Serves as a fallback flight data source under the ODbL 1.0 license when OpenSky is unavailable.
• AISStream.io: Supplies live AIS vessel positions via a free beta public broadcast service.

Space and Environmental Monitoring

• CelesTrak: Offers satellite TLEs for SGP4 propagation. US-government data requires citation to Dr. T.S. Kelso, CelesTrak (celestrak.org).
• The Space Devs – Launch Library 2 v2.3: Provides recent launch, payload, and recovery metadata for a 30-day window. Open use with attribution encouraged.
• NASA FIRMS: Delivers live fire observations when configured with a free MAP KEY. Data is CC0 / US public domain.
• USGS: Supplies earthquake data in the public domain.

Basemaps and Geographic Context

• Google Map Tiles API (Photorealistic 3D Tiles): Powers the primary 3-D globe, Places, and Geocoding features under proprietary Google Maps Platform ToS.
• Esri World Imagery: Default satellite basemap when no Google API key is configured. Requires attribution per the Esri Master Agreement.
• OpenStreetMap (Overpass API): Provides road geometry for traffic visualization and reverse-geocoding under ODbL 1.0.

Weather, News, and Infrastructure

• Open-Meteo: Current weather data for UI and atmospheric effects under CC BY 4.0.
• Google News RSS: Locality-matched headlines restricted to personal, non-commercial use per Google News ToS.
• GDELT Project DOC 2.0: Fallback news feed with unrestricted academic/commercial use requiring citation.
• City-Specific CCTV: Camera catalogs from City of Austin Open Data, Caltrans, and TfL Open Data (JamCams) under respective open-data licenses.

Transportation and Recreation

• GBFS (Lyft/BCycle): Bikeshare availability with per-feed attribution requirements.
• Radio Browser: Geolocated internet-radio directory under PDDL 1.0 (public domain).
• Re:Earth Terrain (Mapterhorn): Terrain mesh and geoid heights for keyless globe stacks. Mesh is CC BY 4.0; geoid uses public-domain EGM2008 (NGA).

Bundled Static Datasets

Located in src/data/local_data/, these committed GeoJSON and JSON files enable offline functionality without network access. Each directory contains its own README.md detailing provenance and licensing.

Dataset	Folder	License	Commercial Use	Attribution
Datacenters (~4.3K)	datacenters/	ODbL 1.0	✅ (Share-Alike)	© OpenStreetMap contributors
Dams (704)	dams/	ODbL 1.0	✅ (Share-Alike)	© OpenStreetMap contributors + Open Infrastructure Map
TeleGeography Submarine Cable Map	telegeography_submarine_cables/	CC BY-NC-SA 3.0	❌ Non-commercial only	© TeleGeography — submarinecablemap.com
Natural Earth physical regions	natural_earth/	Public Domain	✅ (No restrictions)	Made with Natural Earth
DataSF Analysis Neighborhoods	neighborhoods/	PDDL 1.0	✅ (No restrictions)	City & County of San Francisco — DataSF

The TeleGeography dataset requires particular attention: its CC BY-NC-SA 3.0 license prohibits commercial use. Deployments for commercial purposes must remove this folder from src/data/local_data/.

Attribution and Proxy Architecture

All data sources route through a unified attribution manager. The src/data/dataCredits.js module registers each source’s credit string at startup, injecting them into the Cesium credit line (#cesium-credits) and the expandable Data Attribution pop-over.

Server-side proxies in src/api/*.mjs—such as src/api/flight.mjs and src/api/terrain/heights.mjs—fetch live data, respect rate limits, and forward JSON payloads to the frontend.

To register a new attribution:

// src/data/dataCredits.js
export const DATA_CREDITS = [
  new Cesium.Credit(
    '<a href="https://example.com" target="_blank">Example Data Source</a>',
    false
  )
];

Working with Data Sources

Loading Bundled Datasets

Static datasets are imported directly by client-side modules. The src/data/naturalEarthRegions.js file demonstrates how to consume bundled GeoJSON:

// src/data/naturalEarthRegions.js
import regions from './local_data/natural_earth/regions.json' assert {type: 'json'};
import marine from './local_data/natural_earth/marine.json' assert {type: 'json'};

export const getRegionByName = (name) =>
  regions.features.find(f => f.properties.NAME === name);

Usage in a Cesium application:

import { getRegionByName } from './data/naturalEarthRegions.js';

const alps = getRegionByName('Alps');
viewer.entities.add({
  polygon: {
    hierarchy: Cesium.Cartesian3.fromDegreesArray(alps.geometry.coordinates[0]),
    material: Cesium.Color.BLUE.withAlpha(0.4)
  }
});

Querying Live APIs

Live sources are accessed via server-side proxies. The OpenSky implementation in src/api/openSky.mjs fetches flight states:

// src/api/openSky.mjs
export async function fetchOpenSky(lat, lon, radiusKm = 250) {
  const url = `https://opensky-network.org/api/states/all?lamin=${lat - 1}&lomin=${lon - 1}&lamax=${lat + 1}&lomax=${lon + 1}`;
  const resp = await fetch(url);
  if (!resp.ok) throw new Error('OpenSky request failed');
  const data = await resp.json();
  return data.states; // array of live flight states
}

Frontend consumption:

import { fetchOpenSky } from '../api/openSky.mjs';

(async () => {
  const flights = await fetchOpenSky(37.7749, -122.4194);
  console.log(`Found ${flights.length} flights around San Francisco`);
})();

Summary

• Hybrid Architecture: God’s-Eye-View combines live APIs (fetched at runtime) with bundled snapshots (stored in src/data/local_data/) to balance real-time accuracy with offline reliability.
• Attribution Automation: The src/data/dataCredits.js system ensures all twenty-plus sources—ranging from Google Map Tiles to NASA FIRMS—display required credits in the Cesium globe interface.
• License Diversity: Sources range from public domain (USGS, Natural Earth) to share-alike (OpenStreetMap ODbL) to non-commercial (TeleGeography), requiring careful compliance review for commercial deployments.
• Server-Side Proxies: All live data flows through cached proxy endpoints (e.g., /api/flight) to manage rate limits and API keys securely.

Frequently Asked Questions

Does gods-eye-view store API data locally?

No. Live runtime sources such as OpenSky, Google Maps, and Open-Meteo are fetched on-demand through server-side proxies and are not committed to the repository. Only the five bundled datasets in src/data/local_data/ (Natural Earth, TeleGeography cables, datacenters, dams, and SF neighborhoods) are stored locally as GeoJSON.

Can I use gods-eye-view commercially given the mixed licenses?

Partially. While most sources (OpenStreetMap, USGS, Natural Earth) permit commercial use with attribution, the TeleGeography Submarine Cable Map is strictly CC BY-NC-SA 3.0 (non-commercial only). Commercial deployments must delete the src/data/local_data/telegeography_submarine_cables/ directory. Additionally, Google News RSS restricts usage to personal, non-commercial applications.

How do I add a new data source to gods-eye-view?

Create a server-side proxy in src/api/ (e.g., newSource.mjs) to handle authentication and caching, then register the attribution in src/data/dataCredits.js using new Cesium.Credit(htmlString, false). For bundled data, add GeoJSON files to src/data/local_data/newfolder/ with a README.md detailing the license and provenance.

What is the caching strategy for live APIs?

Server-side proxies cache responses for 5–15 minutes to respect provider rate limits and improve performance. The cache duration varies by source volatility; flight data (OpenSky) updates more frequently than static infrastructure catalogs (Caltrans CCTV).

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