The Embeddings API helps you search and analyze remotely sensed imagery through embeddings created by geospatial foundational models (GEOFMs); making it easy to find similar locations, track changes over time, explore geographic areas, and much more!

This guide covers everything you need to get started: obtaining credentials; creating tenants, collections and indexes; as well as running your first searches.

Key Concepts:

• Tenant: Organizational unit that own collections and indexes.

• Collection: Embeddings generated from imagery for a geographic area and time range.

• Index: A vector index built on top of a collection that enables fast similarity search.

• Chip: A small geographic tile cut from an image. Each chip has an embedding vector and a capture timestamp. Chips are spatially and temporally unique, whereas cells are only spatially unique.

   

API Reference

This is the location of our full API reference: https://embeddings.api.lgnd.ai/v1/reference

This is also linked in our Developer Portal for easy access.

Step 1: Get Your API Credentials

All API requests require a Bearer token. To obtain one:

1. Visit the LGND Developer Portal at https://developer.lgnd.ai
2. Create an account and sign in.
3. Copy your API token from the portal.

💡  Tip: Store the token in an environment variable so you can reuse it across all examples in this guide:

export LGND_TOKEN="your_api_token_here"

Step 2: Manage Tenants

A tenant is used to separate data collections and every operation in the API is scoped to a tenant. You need at least one tenant before you can list collections or run searches.

Please see the tenants section of our API Reference for the full list of operations, proper request syntax and expected responses.  

Step 3: Browse Collections

Collections contain the generated embeddings you will search against. Each embedding is associated with a chip. A chip is defined by a geometry, a sensor and a timestamp.

To get you started, we have included access to several collections with pre-generated embeddings and a ready-to-use index. Ready-to-use collections include:

• California, USA; NAIP, 2020 - 2022.
• France; Sentinel-2; June 2024 and June 2025

Please see the collections section of our API Reference for the full list of operations, proper request syntax and expected responses.  

Of particular note, the post create_collection is the mechanism to create embeddings from source imagery.

Step 4: Create Indexes

In order to search across a collection, an index must be created. Indexes can only be created after the parent collection reaches READY status.

Please see the indexes section of our API Reference for the full list of operations, proper request syntax and expected responses.  

LGND automatically optimizes the index provider and all index parameters based on the collection to enable an clear, straightforward experience for the user.  

Step 5: Run Searches

The LGND API provides four search operations and one filter operation — all available at no cost to every user. Every search requires a READY collection and its associated index.

Please see the search section of our API Reference for the full list of operations, proper request syntax and expected responses.  

Search Operations at a Glance

Many of the operations involve search across chips. As a reminder, a chip is a small geographic tile cut from a satellite image and each chip has an embedding vector and a capture timestamp.

All search responses contain a data array of results sorted by similarity score, and a _meta object with timing information and the distance metric used (cosine).

Search by Chip  (Recommended Starting Point)

This is the easiest way to start. Pick a chip ID from a collection and find the top k chips that are  visually similar to it, i.e. that have the highest cosine similarity scores.

Below is an example request:

curl -X POST \
  https://embeddings.api.lgnd.ai/v1/tenants/{tenant_id}/collections/{collection_id}/search-by-chip \
  -H "Authorization: Bearer $LGND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chips_id": "chip_018d5e5a5c8b7890a1b2c3d4e5f6a7b8",
    "top_k": 10
  }'

Search by Location

Find chips near a specific latitude/longitude coordinate. Optionally narrow results to a date range.

Below is an example request:

curl -X POST \
  https://embeddings.api.lgnd.ai/v1/tenants/{tenant_id}/collections/{collection_id}/search-by-location \
  -H "Authorization: Bearer $LGND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 30.25,
    "longitude": -97.65,
    "start_date": "2023-01-01",
    "end_date": "2023-12-31",
    "top_k": 10
  }'

Search for Changed Chips

Detect semantic or visible change in an area by comparing historical chips against the most recent chips with text or chip references. Results are returned as pairs (past chip + current chip) sorted by change score.

Each result in data is a changed_chip_pair containing chip_past, chip_current, a shared cell_id, and a score.

curl -X POST \
  https://embeddings.api.lgnd.ai/v1/tenants/{tenant_id}/collections/{collection_id}/search-changed-chips \
  -H "Authorization: Bearer $LGND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "positive_texts_past": ["green vegetation"],
    "positive_texts_current": ["bare soil, cleared land"],
    "top_k": 10
  }'

Filter by Geometry

Retrieve all chip IDs whose footprint intersects a GeoJSON polygon, ordered by capture date (newest first). Unlike search operations, this returns chip IDs only — no similarity scores.

Below is an example request:

curl -X POST \
  https://embeddings.api.lgnd.ai/v1/tenants/{tenant_id}/collections/{collection_id}/filter-by-geometry \
  -H "Authorization: Bearer $LGND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "geometry": {
      "type": "Polygon",
      "coordinates": [[
        [-97.7, 30.2], [-97.7, 30.3],
        [-97.6, 30.3], [-97.6, 30.2],
        [-97.7, 30.2]
      ]]
    },
    "limit": 100
  }'

Troubleshooting

Below are a list of common error responses from the API and the associated solution steps:

Next Steps

Once you are comfortable searching the free-tier collections, you may want to:

• Explore the full interactive API reference at https://embeddings.api.lgnd.ai/v1/reference.
• Build a change detection workflow by combining search-changed-chips with periodic automated requests over a region of interest.
• Upgrade to a paid tier to create custom collections and indexes over a larger area of interest and date range.