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

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. 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:

echo "GOOGLE_MAPS_API_KEY=YOUR_GOOGLE_MAPS_KEY_HERE" >> .env

After saving, reload the application environment:

npm run dev

Upon restart, 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 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:

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 — 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 — 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 — 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.

Summary

• Environment Variable: The application strictly requires GOOGLE_MAPS_API_KEY in the environment or .env file.
• Entry Point: 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, 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 or any other tracked file, as the application is designed to read credentials exclusively from the environment.

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