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

Set the GOOGLE_MAPS_API_KEY environment variable in a .env file or paste it into the POWER UP panel's Provider Settings to enable Google Photorealistic 3D tiles, Street View panoramas, and geocoding in God's Eye View.

God's Eye View leverages the Google Maps Platform to render photorealistic 3D environments, fetch Street View imagery, and perform geocoding operations. The application expects your API key as the environment variable GOOGLE_MAPS_API_KEY, which is injected client-side at runtime without ever being committed to version control.

This guide covers three configuration methods—environment files, the in-app UI, and programmatic scripts—along with the underlying implementation details from the bilawalsidhu/gods-eye-view source code.

Why You Need a Google Maps API Key

Without a valid key, God's Eye View falls back to Cesium Ion-hosted Google assets with limited functionality. Supplying your own GOOGLE_MAPS_API_KEY unlocks the full Google Maps Platform integration:

• Photorealistic 3D Tiles via Cesium.createGooglePhotorealistic3DTileset
• Street View Panoramas fetched through tools/streetview-panorama.mjs
• Satellite Orthophotos retrieved via tools/sat-ortho.mjs
• Geocoding Services used in src/locations.js for place searches

When the key is missing, the interface displays a tooltip warning "Google 3D tiles unavailable — needs GOOGLE_MAPS_API_KEY" and restricts access to high-resolution 3D data.

Method 1: Configure via Environment Variable

The recommended approach for local development uses a .env file ignored by Git. This method ensures your key persists across sessions without exposing it in the repository.

Create or edit .env in the project root:

echo "GOOGLE_MAPS_API_KEY=YOUR_GOOGLE_MAPS_KEY_HERE" >> .env

Restart the development server to load the new environment:

npm run dev

The application reads this variable during startup in src/mapStartup.js, which sets Cesium.GoogleMaps.defaultApiKey before initializing the tileset. You can verify the template format in .env.example included in the repository root.

Method 2: Configure via the POWER UP UI Panel

For users who prefer graphical configuration or need to rotate keys without editing files, God's Eye View provides an in-app settings interface.

1. Launch the application at http://localhost:4173
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 automatically restarts with the new credentials loaded. This UI method writes the key to the runtime environment, triggering the same initialization logic in src/mapStartup.js that creates the Cesium.createGooglePhotorealistic3DTileset instance when GOOGLE_MAPS_API_KEY is detected.

Method 3: Programmatic Configuration for CLI Tools

Custom scripts and command-line tools within the repository can resolve the API key programmatically using the provided utility module.

Import the resolver in your script:

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

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

Pass the resolved key to CLI tools that accept the --key flag:

node tools/streetview-panorama.mjs --key="$key" --lat=40.7484 --lon=-73.9857

This approach is essential when running tools/sat-ortho.mjs for bulk satellite tile fetching, as both tools default to reading GOOGLE_MAPS_API_KEY from the environment but can accept explicit key parameters for automated workflows.

How the Application Uses Your Key

Understanding the internal data flow ensures you configure the correct permissions for your Google Cloud project.

In src/mapStartup.js, the startup sequence checks for process.env.GOOGLE_MAPS_API_KEY. If present, the code executes:

Cesium.GoogleMaps.defaultApiKey = process.env.GOOGLE_MAPS_API_KEY;
const tileset = await Cesium.createGooglePhotorealistic3DTileset();

The src/locations.js module uses the same variable for geocoding requests, throwing "No Google Maps API key available for geocoding" if the key is absent. Meanwhile, tools/streetview-panorama.mjs and tools/sat-ortho.mjs read GOOGLE_MAPS_API_KEY to authenticate requests to the Google Map Tiles API for Street View metadata and satellite imagery respectively.

Importantly, the key is only used client-side; the repository contains no server-side secrets, and .gitignore explicitly excludes .env files to prevent accidental credential leakage.

Troubleshooting Missing Key Errors

If you encounter the "Google 3D tiles unavailable" warning after configuration:

• Verify the variable name matches exactly: GOOGLE_MAPS_API_KEY (not GOOGLE_MAPS_KEY or API_KEY)
• Confirm the .env file is in the project root, not a subdirectory
• Check that you restarted the dev server after editing environment variables
• Ensure your Google Cloud project has the Map Tiles API and Geocoding API enabled

The UI tooltip appears whenever Cesium.GoogleMaps.defaultApiKey remains undefined, which occurs if the environment variable is empty or inaccessible to the Vite build process.

Summary

• Primary Variable: God's Eye View requires GOOGLE_MAPS_API_KEY set in your environment or via the POWER UP panel to enable full 3D mapping capabilities
• Configuration Options: Use a .env file for development, the POWER UP UI for quick changes, or resolveGoogleServerKey() for scripting
• Key Implementation Files: src/mapStartup.js initializes Cesium with your key, while src/locations.js, tools/streetview-panorama.mjs, and tools/sat-ortho.mjs consume it for specific API calls
• Security: The key is client-side only; never commit .env files to the bilawalsidhu/gods-eye-view repository

Frequently Asked Questions

Do I need to enable specific APIs in Google Cloud Console?

Yes. You must enable the Map Tiles API for 3D tiles and satellite imagery, the Street View Static API for panorama access, and the Geocoding API for location search functionality. All three are required for full functionality in God's Eye View.

Is the Google Maps API key stored securely?

The key is injected into the client-side application at runtime and is visible in browser network requests, which is standard for Google Maps web implementations. However, God's Eye View never commits the key to Git, and the .env.example file shows only the variable name without values.

Can I use God's Eye View without a Google Maps API key?

You can run the application, but 3D tiles and geocoding features will be disabled. The map will fall back to Cesium Ion-hosted Google assets with limited resolution, and the UI will display persistent warnings about missing API credentials.

Why does the application restart when I save the key in the UI?

The POWER UP panel triggers a full application reload to ensure src/mapStartup.js re-executes with the new GOOGLE_MAPS_API_KEY value, properly initializing Cesium.GoogleMaps.defaultApiKey and the photorealistic tileset from the start of the render loop.

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