---
title: Quickstart
---

# Quickstart

Get up and running with Xee in a few minutes.

## 1. Install

```bash
pip install --upgrade xee
```

Optional (plotting): `pip install matplotlib`. For full installation options, see [Installation](installation.md).

## 2. Earth Engine access

You need an Earth Engine–enabled Google Cloud project. If you haven't done this yet, follow the Earth Engine [Access guide](https://developers.google.com/earth-engine/guides/access#get_access_to_earth_engine).

Authenticate once on a persistent machine:

```bash
earthengine authenticate
```

Or inside ephemeral environments (e.g. Colab):

```python
import ee
ee.Authenticate()
```

Initialize (high-volume endpoint recommended for reading stored collections):

```python
import ee
ee.Initialize(
    project='YOUR-PROJECT-ID',
    opt_url='https://earthengine-highvolume.googleapis.com'
)
```

For computed collections (server-side expressions), omit `opt_url` to use the standard endpoint, which benefits from caching during iterative development.

## 3. Open your first dataset

```python
import ee, xarray as xr
from xee import helpers

ic = ee.ImageCollection('ECMWF/ERA5_LAND/MONTHLY_AGGR')
grid = helpers.extract_grid_params(ic)  # match source projection & resolution
ds = xr.open_dataset(ic, engine='ee', **grid)
print(ds)
```

```{admonition} Choosing a grid strategy quickly
:class: tip

- Exploratory analysis: use `helpers.extract_grid_params(...)`.
- Fixed output shape (for model inputs): use `helpers.fit_geometry(..., grid_shape=...)`.
- Fixed physical resolution: use `helpers.fit_geometry(..., grid_scale=...)`.
- Manual `crs` / `crs_transform` / `shape_2d`: advanced alignment workflows only.
```

```{admonition} Dataset ID input forms
:class: note

Xee accepts both plain Earth Engine asset IDs (for example,
`ECMWF/ERA5_LAND/MONTHLY_AGGR`) and URI forms (for example,
`ee://ECMWF/ERA5_LAND/MONTHLY_AGGR`).
```

```{admonition} Where do these parameters come from?
:class: tip

`xr.open_dataset(..., engine='ee')` is the primary user entrypoint for Xee.
For the complete, canonical parameter reference (including defaults and backend
behavior), see [Open Dataset Reference](open_dataset.md).
```

Plot the first time slice (matplotlib required):

```python
ds['temperature_2m'].isel(time=0).plot()
```

## 4. Next steps

| Goal | Where to go |
|------|-------------|
| Learn grid parameter patterns | [Concepts](concepts.md) |
| Fit a custom area or scale | [User Guide](guide.md) |
| API signatures | [API Reference](api.md) |
| Migrate 0.0.x code | [Migration Guide](migration-guide-v0.1.0.md) |
| Performance tips | [Performance & Limits](performance.md) |
| Troubleshooting common issues | [FAQ](faq.md) |

## 5. Minimal workflow recap

1. Install Xee & authenticate EE
2. Initialize EE client
3. Derive grid parameters (match source or fit a geometry)
4. Call `xr.open_dataset(..., engine='ee', **grid)`
5. Use Xarray normally (select, compute, visualize, export)

## 6. Example: custom AOI at fixed size

AOI means area of interest.

```python
import shapely
from xee import helpers

aoi = shapely.geometry.box(113.33, -43.63, 153.56, -10.66)  # Australia
grid = helpers.fit_geometry(
    geometry=aoi,
    grid_crs='EPSG:4326',   # degrees
    grid_shape=(256, 256)   # (width, height) pixels
)

ds = xr.open_dataset('ee://ECMWF/ERA5_LAND/MONTHLY_AGGR', engine='ee', **grid)
```

## 7. Having trouble?

See the [FAQ](faq.md) and open a [discussion](https://github.com/google/Xee/discussions) if needed.