EmbedEarth is an open, programmable geographic layer for physical-world data. Use one SDK to search places and observations, run spatial analysis, build routes, render maps, and work with local data.

Install

npm install @embedearth/sdk

Use @embedearth/sdk/node for Stratum and filesystem-backed work.

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. Create a key at embed.earth and pass it as apiKey; a key is also required for Street View image access.

const e2 = new E2({ apiKey: process.env.E2_API_KEY });

Search

Search returns a GeoJSON FeatureCollection. feature is a canonical feature key or numeric ID; use area for a name, area_id for an exact ID, coordinates for a point lookup, or country_code and state_code for code-based area selection.

Optional parameters

Parameter	Type	Purpose
`area`	`string \| string[]`	Search one or more named areas. Mutually exclusive with `area_id`.
`area_id`	`string \| string[]`	Search one or more exact area IDs. Mutually exclusive with `area`.
`country_code`	`string`	Select a country, for example `US`.
`state_code`	`string`	Select a state or province, for example `NY`.
`latitude`, `longitude`	`number`	Search around a coordinate. Provide both.
`mode`	`"cloud" \| "offline" \| "auto"`	Select the execution mode. Defaults to `auto`.
`limit`	`number`	Maximum number of returned features. Defaults to `1000`.
`cacheDirectory`	`string`	Override the local Stratum cache directory.
`signal`	`AbortSignal`	Cancel the request.

await e2.search({ feature: "restaurant", area: "New York", mode: "auto" });
await e2.search({ feature: "restaurant", area_id: "4915", mode: "cloud" });
await e2.search({ feature: "restaurant", latitude: 40.7128, longitude: -74.006, mode: "cloud" });
await e2.search({ feature: "restaurant", country_code: "US", state_code: "NY", mode: "cloud" });

Compute

Compute returns spatial analysis instead of raw records. feature is what is measured and area or area_id is the scope; relation methods such as near name 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.

await e2.compute.feature("restaurant").areaId("4915").near("park", 500).count();
await e2.compute.feature("restaurant").area("New York").near("park", 500).density();
await e2.compute.run({ primitive: "COUNT", feature: "restaurant", latitude: 40.7128, longitude: -74.006 });

Routing

Routing builds directions and network-analysis responses from coordinates or indexed features. It supports feature routes, direct routes, matrices, isochrones, map matching, locate, and height.

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

Function	Purpose
`e2.route.feature(...).from(...).nearest(...)`	Route from a coordinate to a matching feature, such as the closest restaurant.
`e2.route.route(...)`	Build a route between one or more coordinates.
`e2.route.matrix(...)`	Return travel costs between multiple sources and targets.
`e2.route.isochrone(...)`	Calculate the area reachable within one or more time limits.
`e2.route.mapMatch(...)`	Match a recorded coordinate trace to the road network.
`e2.route.locate(...)`	Resolve a coordinate to the routable network.
`e2.route.height(...)`	Return elevation data for one or more locations.

const e2 = new E2({ routeUrl: "https://your-router.example" });
await e2.route.feature("restaurant").from({ lat: 40.7128, lon: -74.006 }).nearest({ mode: "walking" });
await e2.route.matrix({ sources: [{ lat: 40.7128, lon: -74.006 }], targets: [{ lat: 40.7306, lon: -73.9352 }] });
await e2.route.isochrone({ locations: [{ lat: 40.7128, lon: -74.006 }], contours: [{ time: 10 }, { time: 20 }] });

Maps

Maps returns MapLibre-ready Planet and feature PMTiles source descriptors. Use @embedearth/sdk/map when you want browser rendering.

const sources = await e2.map.sources(["restaurant"]);

Stratum

Stratum provides geographic lookup, published data discovery, verified caching, downloads, local queries, and namespaced local uploads. Use it from the Node entry point for local GeoJSON, CSV, Parquet, and SQLite workflows.

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

import { E2, stratum } from "@embedearth/sdk/node";
const local = new E2({ cacheDirectory: "./.e2" });
await local.stratum.download({ feature: "restaurant", regionId: "4915" });
await local.stratum.upload({ path: "./stores.geojson", database: "./stores.db", feature: "stores", namespace: "my-app" });
const standalone = stratum({ cacheDirectory: "./.e2" });

Geographical Features

Geographical features are the canonical physical-world types used across the SDK, such as restaurants, 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.