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

> Explore Gods-Eye-View data sources: leverage 20+ live APIs like Google Maps & OpenSky alongside static datasets from Natural Earth & TeleGeography.

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

---

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

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/naturalEarthRegions.js) file demonstrates how to consume bundled GeoJSON:

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

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

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

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