EmbedEarth is an open, programmable geographic layer for physical-world data. The earth CLI brings Search, Compute, Routing, Maps, and Stratum to terminals, scripts, and automation.

Install

npm install -g @embedearth/cli

Modes

Mode	Purpose
`auto`	Use verified local Stratum data first, then run the function in Cloud.
`offline`	Use only verified local data and make no network request.
`cloud`	Run the function in EmbedEarth Cloud. A key is optional, but unauthenticated use is heavily limited.

API key and limits

An API key is optional. Cloud Search, Compute, and Route requests are limited to 60 requests per minute without a key, or 2,000 requests per minute with a key. stratum query without a key should be treated as one request per second. A key is also required for Street View image access. Get one at embed.earth, then set E2_API_KEY.

$env:E2_API_KEY = "your_api_key"

Search

Search returns a GeoJSON FeatureCollection. The positional feature arguments are canonical feature keys or IDs; use --area for a name, --area-id for an exact ID, or country/state codes for code-based area selection.

Optional parameters

Option	Purpose
`--area <area>`	Search one or more named areas.
`--area-id <id>`	Search one or more exact area IDs.
`--country-code <code>`	Select a country, for example `US`.
`--state-code <code>`	Select a state or province, for example `NY`.
`--latitude <degrees>`, `--longitude <degrees>`	Search around a coordinate. Provide both.
`--mode <mode>`	Use `cloud`, `offline`, or `auto`; defaults to `auto`.
`--limit <number>`	Maximum number of returned features; defaults to `1000`.
`--json`	Print machine-readable JSON.

earth search restaurant --area "New York" --mode auto --limit 25 --json
earth search restaurant hospital --area-id 4915 --mode cloud --json
earth search restaurant --country-code US --state-code NY --mode cloud --json
earth search restaurant --latitude 40.7128 --longitude -74.006 --mode cloud --json

Compute

Compute returns spatial analysis instead of raw records. The feature arguments are what is measured, --area or --area-id is the scope, and --near or --within names the related feature.

Primitive	Purpose
`nearest`	Find the closest features.
`distance`	Measure distance between feature sets.
`within`	Select features inside a relation distance.
`count`	Count related features.
`density`	Measure feature concentration.
`coverage`	Measure reached area.
`gaps`	Find unreached areas.
`cluster`	Group nearby features.

earth compute count restaurant --area-id 4915 --near park --distance 500 --mode cloud --json
earth compute density restaurant --area "New York" --near park --distance 500 --mode auto --json

Routing

Routing builds directions and network-analysis responses from coordinates or indexed features. Use to-feature for a coordinate-to-feature route; route, matrix, isochrone, map-match, and request cover other routing operations.

Set ROUTE_URL only when you want a custom compatible routing service.

Command	Purpose
`earth route to-feature`	Route from a coordinate to a matching feature, such as the closest restaurant.
`earth route run`	Build a route between one or more coordinates.
`earth route matrix`	Return travel costs between multiple sources and targets.
`earth route isochrone`	Calculate the area reachable within one or more time limits.
`earth route map-match`	Match a recorded coordinate trace to the road network.
`earth route request`	Send another compatible routing operation.

$env:ROUTE_URL = "https://your-router.example"
earth route to-feature restaurant --from "40.7128,-74.006" --mode walking --json
earth route matrix --sources "40.7128,-74.006" --targets "40.7306,-73.9352" --mode driving --json
earth route isochrone --locations "40.7128,-74.006" --contours "10,20" --json

Maps

Maps prepares MapLibre-ready source descriptors for the Planet basemap and feature layers. It returns data for a map client; it does not render a terminal map.

earth map sources restaurant hospital --json

Stratum

Stratum provides geographic lookup, published data discovery, verified caching, downloads, local queries, and namespaced local uploads. It is useful for repeatable local data workflows and user-owned GeoJSON, CSV, and Parquet features.

Command family	Purpose
`stratum cache`	Manage verified local data.
`stratum features` / `areas`	Look up built-in inputs.
`stratum data`	Inspect published data.
`stratum download` / `query`	Pull and query Cloud or local data.
`stratum upload`	Add namespaced local data.

earth stratum areas search "New York" --json
earth stratum download restaurant --area-id 4915 --out ./restaurants.parquet
earth stratum upload ./stores.geojson --db ./stores.db --feature stores --namespace my-app --json

Geographical Features

Geographical features are the canonical physical-world types used across the CLI, including places, infrastructure, observations, and imagery-linked records. Browse them at Catalog Features.

Geographical Areas

Geographical areas are countries, states, cities, and other regions used to scope data. Browse names and stable IDs at Catalog Areas.

Street View Images

EmbedEarth ingests billions of Street View images and discovers new features or where imagery pairs with reported places. Street View is Cloud-only for now because of cost; an API key and an active subscription are required for unlimited use.