# How to Set Up a Google Maps API Key in God's Eye View: Complete Configuration Guide

> Learn how to set up your Google Maps API key in God's Eye View. This guide shows you how to configure the GOOGLE_MAPS_API_KEY environment variable for 3D tiles, Street View, and geocoding.

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

---

**God's Eye View reads your Google Maps API key from the `GOOGLE_MAPS_API_KEY` environment variable to enable photorealistic 3D tiles, Street View panoramas, and geocoding via the Google Maps Platform.**

God's Eye View is an open-source geospatial visualization application by bilawalsidhu that integrates Cesium with Google Maps Platform services. To unlock the full photorealistic 3D experience and location search capabilities, you must configure a valid Google Maps API key using one of several supported methods. This guide explains exactly where the application reads your credentials and how to provide them correctly based on the source code implementation.

## Where God's Eye View Expects the API Key

The application follows a strict environment-variable pattern defined in [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js). When the app initializes, it checks for `process.env.GOOGLE_MAPS_API_KEY` and assigns it to `Cesium.GoogleMaps.defaultApiKey`. If present, the loader immediately creates a `GooglePhotorealistic3DTileset` via `Cesium.createGooglePhotorealistic3DTileset`; if absent, the UI displays a tooltip stating "Google 3D tiles unavailable — needs `GOOGLE_MAPS_API_KEY`" and falls back to a Cesium Ion-hosted Google asset.

CLI tools in the repository also rely on this variable. Both `tools/streetview-panorama.mjs` and `tools/sat-ortho.mjs` import a resolver that defaults to `GOOGLE_MAPS_API_KEY` when the `--key` flag is omitted. The key is used exclusively client-side; no secrets are ever committed to the repository, as confirmed by the `.gitignore` rules and `.env.example` template.

## How to Configure the Google Maps API Key

You can inject the API key into God's Eye View using three distinct methods: a local `.env` file, the in-app POWER UP panel, or programmatically for scripting.

### Method 1: Using a Local .env File

Create a `.env` file in the project root (this file is ignored by Git) and define the variable:

```bash
echo "GOOGLE_MAPS_API_KEY=YOUR_GOOGLE_MAPS_KEY_HERE" >> .env

```

After saving, reload the application environment:

```bash
npm run dev

```

Upon restart, [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js) will detect the variable and initialize the Google Photorealistic 3D tileset automatically.

### Method 2: Using the In-App POWER UP Panel

For users running the compiled application:

1. Navigate to `http://localhost:4173` (or your deployed instance)
2. Click the **POWER UP** chip in the interface
3. Select **Provider Settings**
4. Paste your key into the *Google Maps* input field
5. Press **SAVE KEYS**

The application restarts automatically with Google 3D tiles enabled. This UI method writes the value to the runtime environment that [`src/locations.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/locations.js) uses for subsequent Google Geocoding API calls.

### Method 3: Programmatic Access for CLI Tools

When writing custom scripts or using the provided CLI utilities, resolve the key programmatically:

```javascript
import { resolveGoogleServerKey } from './scripts/google-server-key.mjs';

const key = resolveGoogleServerKey({ 
  env: process.env, 
  fromDotenv: true 
});

// Use with CLI tools
// node tools/streetview-panorama.mjs --key ${key} --lat 40.7128 --lng -74.0060

```

The `resolveGoogleServerKey` function automatically falls back to the `GOOGLE_MAPS_API_KEY` environment variable when no explicit key is provided.

## Key Source Files and Implementation Details

Understanding these specific files helps debug configuration issues:

- **[`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js)** — Reads `GOOGLE_MAPS_API_KEY` from the environment and initializes `Cesium.GoogleMaps.defaultApiKey`. Also handles the creation of the photorealistic 3D tileset.
- **[`src/locations.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/locations.js)** — Consumes the key for Google Geocoding API requests; throws "No Google Maps API key available for geocoding" if the variable is undefined.
- **`tools/streetview-panorama.mjs`** — CLI utility that queries Street View panoramas; defaults the `--key` parameter to the environment variable.
- **`tools/sat-ortho.mjs`** — Fetches satellite orthoimagery via the Google Map Tiles API using the same key resolution logic.
- **`.env.example`** — Template file demonstrating the exact variable name (`GOOGLE_MAPS_API_KEY=`) required by the application.
- **[`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md)** — Contains the user-facing API key documentation referencing the POWER UP panel workflow.

## Troubleshooting and Validation

If the 3D tiles fail to load, verify that the variable name matches exactly: `GOOGLE_MAPS_API_KEY` (not `GOOGLE_MAPS_KEY` or `API_KEY`). Check the browser console and the terminal running `npm run dev` for the specific tooltip message: "Google 3D tiles unavailable — needs `GOOGLE_MAPS_API_KEY`".

Ensure your Google Cloud project has the **Map Tiles API**, **Street View Static API**, and **Geocoding API** enabled, as God's Eye View calls all three services through the Cesium integration and the geocoding module in [`src/locations.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/locations.js).

## Summary

- **Environment Variable**: The application strictly requires `GOOGLE_MAPS_API_KEY` in the environment or `.env` file.
- **Entry Point**: [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js) sets `Cesium.GoogleMaps.defaultApiKey` and creates the 3D tileset.
- **UI Method**: Use the **POWER UP** panel → **Provider Settings** for runtime configuration.
- **CLI Support**: Tools like `streetview-panorama.mjs` and `sat-ortho.mjs` reuse the same variable via `resolveGoogleServerKey`.
- **Security**: Keys are client-side only; repository contains no hardcoded secrets.

## Frequently Asked Questions

### What happens if I don't provide a Google Maps API key?

Without the `GOOGLE_MAPS_API_KEY` variable, God's Eye View displays a tooltip warning that "Google 3D tiles unavailable" and automatically falls back to Cesium Ion-hosted Google assets. You will lose access to photorealistic 3D buildings, Street View imagery, and Google-powered geocoding search, though basic globe visualization remains functional.

### Can I use the Google Maps API key in server-side scripts with this repository?

Yes. Import the `resolveGoogleServerKey` function from `scripts/google-server-key.mjs` to read the same environment variable used by the frontend. This ensures consistency between your CLI tools (like `sat-ortho.mjs`) and the main application when batch-processing satellite tiles or Street View data.

### Why does the application use Cesium.GoogleMaps.defaultApiKey instead of a custom header?

According to the source code in [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js), setting `Cesium.GoogleMaps.defaultApiKey` is the standard integration pattern for Cesium's Google Maps Platform partner API. This global assignment allows the `Cesium.createGooglePhotorealistic3DTileset` constructor to authenticate automatically without passing the key through every function call.

### Where should I store the API key to avoid committing it to git?

Always store the key in a `.env` file in the project root. The repository's `.gitignore` excludes this file, and `.env.example` provides the correct template. Never paste the key directly into [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js) or any other tracked file, as the application is designed to read credentials exclusively from the environment.