earthquery turns plain English into vector search over satellite imagery embeddings. Type “solar farms in deserts” and get matching locations on a map, ranked by embedding similarity.
Query “solar farms in deserts”
Searching demo index…
Live preview: real demo-index results for “solar farms in deserts”.
How it works
The architecture is the product: an embedding model turns language into vectors, and vector search turns vectors into places. v1 proves the loop on a demo index; the production column shows what replaces each part.
01
“solar farms in deserts” or “golf courses near lakes”. No GIS syntax, no bounding-box math, no band indices.
02
EmbeddingGemma 2 maps text into a shared 768-dim space. The demo uses 64-dim concept vectors from keyword matching behind the identical interface.
03
Every tile is scored against the query vector. The demo ranks 521 tiles; production ranks AlphaEarth's global 10m embeddings in Earth Engine.
04
Top tiles render as map rectangles with scores. GET /api/search returns the same ranking as JSON, so agents skip the UI entirely.
Integration code for both production adapters lives in lib/providers.ts. Demo results are never presented as satellite analysis.
API
Every search the UI performs is a plain GET request. Agents use the same endpoint with no API key in v1, and /llms.txt tells them exactly what the demo index can and cannot do.
curl "https://earthquery-mauve.vercel.app/api/search?q=solar+farms+in+deserts&limit=3"
Parameters
qlimitScores are cosine similarity scaled to 0-100. Every response carries a demo flag and the matched concepts, so agents can tell simulated vectors from measured ones.
{
"query": "solar farms in deserts",
"provider": "demo-concept-embedder",
"dimensions": 64,
"tile_count": 521,
"matched_concepts": ["solar farm", "desert"],
"matched_places": [],
"notice": null,
"demo": true,
"results": [
{
"tile_id": "w-sahara-12",
"bbox": [23.52, 12.84, 23.64, 12.96],
"center": [23.58, 12.9],
"score": 94,
"tags": ["desert", "solar farm"]
}
]
}/api/search?q=…&limit=12Ranked tile matches for a natural-language query. Returns 400 when q is missing.
/api/healthStatus, provider name, vector dimensions, tile count, and coverage.
/llms.txtAgent-readable project description, API summary, and demo status.
FAQ
No. v1 searches a bundled demo index of 521 tiles whose vectors are deterministic concept vectors, not measurements from satellite imagery. The pipeline itself is real: query to embedding to cosine search to ranked tiles. The README documents exactly what is simulated and how to replace it.
EmbeddingGemma 2 (Google, released October 2026, Apache 2.0) turns queries into vectors in a shared multimodal space. AlphaEarth Satellite Embedding V1 (CC-BY 4.0, served in Google Earth Engine) provides 64-dim embeddings per 10m pixel globally. lib/providers.ts contains the integration code for both.
Authenticate the Earth Engine client, sample mean 64-dim embeddings per tile from GOOGLE_SATELLITE_EMBEDDING_V1_ANNUAL, and save the result as data/alphaearth-tiles.json in the Tile shape. The cosine search in lib/search.ts is dimension-agnostic, so no search code changes are needed.
JSON with the query, the provider name, matched concepts, and a ranked results array. Each result carries tile_id, bbox as [south, west, north, east], center as [lat, lng], a 0 to 100 similarity score, and concept tags.
Yes. Add an anchor entry to the ANCHORS array in scripts/generate-tiles.mjs, or widen the Ontario grid bounds, then run node scripts/generate-tiles.mjs and restart the dev server. The index regenerates deterministically from seeds.
The code is MIT. AlphaEarth embeddings are CC-BY 4.0. EmbeddingGemma 2 is Apache 2.0. Map tiles are copyright Esri (World Light Gray basemap).