Installation

Prerequisites

Attention

geeViz uses Google Earth Engine (GEE) for much of its functionality. It requires an active Earth Engine account and associated Google Cloud Platform project ID.

If you have not signed up for GEE, please sign up at the Earth Engine registration page.

Installing Earth Engine API

geeViz will attempt to automatically install the earthengine-api package, but sometimes this fails for various reasons. If automatic installation fails, refer to the official Earth Engine Python installation guide for troubleshooting.

You can manually install the Earth Engine API package:

$ pip install earthengine-api

Installing geeViz

Once the Earth Engine API is installed, install geeViz using pip:

$ pip install geeViz

Authentication and Initialization

While geeViz will attempt to authenticate and initialize GEE automatically, it may not handle all authentication methods correctly. The authentication process changes frequently, so following the official Python installation directions is recommended.

Important

While many examples in geeViz do not explicitly initialize to a project in the example code, we strongly recommend following the best practice of initializing GEE to a project prior to importing any geeViz modules.

Recommended initialization pattern:

 1import ee
 2ee.Initialize(project='your-project-id')
 3import geeViz.geeView as gv
 4
 5# Create a map instance
 6Map = gv.Map
 7
 8# Add Earth Engine data to the map
 9Map.addLayer(someEEImage, {}, 'Some Image')
10
11# Display the map
12Map.view()

Replace 'your-project-id' with your actual Google Cloud Project ID.

Verification

To verify your installation, run the following in a Python shell:

import ee
import geeViz

# Initialize Earth Engine
ee.Initialize(project='your-project-id')

# Test basic functionality
print(f"geeViz version: {geeViz.__version__}")
print("Earth Engine initialized successfully!")

If no errors appear, your installation is complete.

Optional: API Keys for Google Maps & Gemini

Some geeViz features require API keys from Google Cloud. These are entirely optional — core GEE functionality works without them.

Key

Used by

How to get

GEMINI_API_KEY

googleMapsLib.interpret_image(), googleMapsLib.label_streetview(), report LLM narratives (outputLib.reports)

Google AI Studio — click “Create API Key”, select a project, copy the key

GOOGLE_MAPS_PLATFORM_API_KEY

googleMapsLib.geocode(), googleMapsLib.streetview_*(), googleMapsLib.search_places(), googleMapsLib.get_elevation(), googleMapsLib.get_air_quality(), googleMapsLib.get_solar_insights(), etc.

Google Cloud Console — see steps below

Getting a Gemini API Key:

  1. Go to Google AI Studio

  2. Click Create API Key

  3. Select your Google Cloud project (or create one)

  4. Copy the generated key

Getting a Google Maps Platform API Key:

  1. Go to the Google Cloud Console

  2. Select or create a project

  3. Navigate to APIs & Services → Credentials

  4. Click Create Credentials → API Key

  5. Copy the key

  6. (Recommended) Click Edit API Key to restrict it to the APIs you need: Geocoding, Street View Static, Places (New), Elevation, Air Quality, Solar, Roads, Maps Static

Storing your keys:

Create a .env file in your geeViz package directory (alongside geeView.py):

# .env file in your geeViz package directory
GEMINI_API_KEY=your_gemini_api_key_here
GOOGLE_MAPS_PLATFORM_API_KEY=your_maps_platform_key_here

You can also set these as environment variables instead of using a .env file. The .env file is loaded automatically by geeViz.googleMapsLib and geeViz.outputLib.reports when they are imported.

Optional pip extras for advanced features:

$ pip install geeViz[gemini]         # Adds google-genai for AI features
$ pip install geeViz[segmentation]   # Adds torch + transformers for SegFormer
$ pip install geeViz[all]            # Everything

AI-Assisted Development (Optional)

If you use an AI coding assistant — Cursor, VS Code with GitHub Copilot, Claude Code, Windsurf, or similar — geeViz ships with an MCP server that gives the AI live access to geeViz. Instead of generating code from memory (which is often wrong or outdated), the AI can look up real function signatures, read actual example scripts, execute and test code, and inspect your Earth Engine assets.

The mcp SDK is already included as a dependency of geeViz — no extra install needed. Just add a short config file for your editor.

Follow the editor-specific instructions in the MCP Server guide. The whole process takes about two minutes.

Note

The MCP server is entirely optional. geeViz works the same way it always has without it. MCP is for users who want their AI assistant to write better geeViz code.

Next Steps

  • Check out the Examples section for use case example scripts and notebooks

  • Review the API Reference section for detailed code documentation

  • Visit the Module Overview to understand the available modules and their purposes

  • Set up the MCP Server if you use an AI coding assistant