Getting Started

Install the SDK and run your first search, route, and spatial compute. Everything on this page works in local, hosted, or automatic mode.

Documentation navigation

Start with E2

SDK guides

CLI guides

MCP guides

Applications

Framework quickstarts

Prerequisites

E2 requires Node.js 20 or newer and npm. Any operating system that runs Node works. Create a project if you do not have one:

terminal

mkdir my-e2-app && cd my-e2-app
npm init -y

A free account is optional. Local and offline modes need no account at all. Sign up only when you want hosted mode and its API keys.

Install the SDK

terminal

npm install @embed-earth/sdk-test

The browser-safe import selects the HTTP backend in browsers and the Node backend on the server. Node 20 or newer is required.

Your first search

search.ts

import { E2 } from "@embed-earth/sdk-test";

const e2 = new E2({ cacheDirectory: "./.e2-cache" });
const result = await e2.search({
  feature: ["restaurant", "school"],
  area: ["Manhattan", "Queens"],
  mode: "auto",
  limit: 1000,
  columns: ["id", "name", "lat", "lng"],
});

console.log(result.type); // "FeatureCollection"

Pass a feature key, alias, or numeric feature ID. area accepts a name or names and resolves them through the region catalog. auto uses local snapshots when available and otherwise fetches published data.

Add routing

routing.ts

const route = await e2.route.route({
  locations: [
    { lat: 40.74, lon: -73.99 },
    { lat: 40.71, lon: -74.01 },
  ],
  mode: "walking",
});

const area = await e2.route.isochrone({
  locations: [{ lat: 40.74, lon: -73.99 }],
  mode: "walking",
  contours: [{ time: 10 }, { time: 20 }],
});

The same client also provides matrices, map matching, locate, and height. See the routing guide for every operation.

Run compute

compute.ts

const count = await e2.compute.feature("restaurant")
  .region("Manhattan")
  .near("park", 500)
  .count();

const results = await e2.compute.feature(["restaurant", "hospital"])
  .region("e2r:region:nyc")
  .within("school", 1000)
  .limit(100)
  .nearest();

Compute chains region(), near(), within(), and limit() and finishes with a primitive such as count() or nearest(). See the compute guide for all eight primitives.

Choose local or hosted

Mode	How it works	Use when
Local	Data lives in a local SQLite index under your cacheDirectory. Queries run on your machine.	You want offline access, full data ownership, or no per-request cost.
Hosted	The SDK calls E2 hosted APIs over HTTP.	You want zero setup, fresh data, or browser-only apps.
Automatic	mode: "auto" prefers local snapshots and falls back to the network.	You want local speed with hosted data as a safety net.

Point cacheDirectory at a directory you control to enable local data. Omit it for remote-only access. The same mode option appears on search and compute, so one client covers both.

Next steps

CLISearch, route, and compute from the terminal.MCP serverExpose E2 tools to AI agents.Framework quickstartsReact, Next.js, TanStack Start, Astro, Vue, and Nuxt.ApplicationsRender E2 results with Leaflet, MapLibre GL, deck.gl, and mobile SDKs.

All developer interfaces