LGND Embeddings

Extension Package provided by CARTO

This extension integrates the LGND AI Embeddings API into CARTO Workflows, enabling satellite imagery search and analysis powered by geospatial foundational models (GEOFMs).

It exposes the LGND catalog of pre-computed embeddings as Workflows components, so you can find similar locations, detect changes over time, or browse coverage in a given area — directly inside a Workflows pipeline.

Most components require a valid LGND AI account and three credentials: a Tenant ID (ten_...), a Collection ID (col_...) and an API Token (sk_...). You can list the tenant–collection pairs available to your account with the LGND Catalog Browser component. See the LGND Embeddings API reference for additional details.

This extension is available for the BigQuery connector.

LGND Catalog Browser

Description

Lists all tenant–collection pairs available to the authenticated LGND account. Use this component to discover which tenant_id and collection_id values to plug into the rest of the LGND components.

Settings

• API Token: Your LGND API authentication token (sk_...).

Output

• Output table: One row per collection, across all tenants accessible by the token. Includes tenant_id, tenant_name, collection_id, collection_name, collection_status (QUEUED, PROCESSING, READY or FAILED), start_date, end_date, model_name (e.g. clay-v1.5) and imagery_source (e.g. naip, sentinel-2-l2a). Only collections with status READY can be used as inputs to the other LGND components.

LGND Text Search

Description

Performs a similarity search using a natural language text query. The query is converted to an embedding by LGND and matched against the chip embeddings in the selected collection. The top results are returned ordered by similarity.

Optionally, you can constrain the search by date range, by a spatial filter, and by providing positive and/or negative example chips to steer the embedding.

Inputs

• Geometry Filter (optional): A table containing a single Polygon or MultiPolygon used to restrict results to chips intersecting that geometry.

• Positive Examples (optional): A table containing chip IDs whose embeddings should be used as positive examples (the search will be pulled towards these).

• Negative Examples (optional): A table containing chip IDs whose embeddings should be used as negative examples (the search will be pushed away from these).

Settings

• Tenant ID: Your LGND tenant identifier (ten_...).

• Collection ID: The collection to search (col_...).

• API Token: Your LGND API authentication token (sk_...).

• Natural Language Query: Text describing what to search for, e.g. construction site with heavy machinery.

• Top K: Number of results to return. Between 1 and 100. Default: 10.

• Start Date (optional): Only consider imagery captured on or after this date (YYYY-MM-DD).

• End Date (optional): Only consider imagery captured on or before this date (YYYY-MM-DD).

• Geometry Column (optional): Geography column in the Geometry Filter table.

• Positive Chip ID Column (optional): Column in the Positive Examples table containing the chip IDs.

• Negative Chip ID Column (optional): Column in the Negative Examples table containing the chip IDs.

Output

• Output table: The chips ranked by similarity score. Each row contains chip_id, raster_id, cell_id, datetime, score (higher = more similar), distance (cosine distance, lower = more similar), collection, centroid and geometry.

LGND Chip Search

Description

Performs a similarity search using an existing chip's embedding as the query vector. Use this to find locations that look similar to a chip you already know — for example, the top result of a previous Text Search or Location Search.

Inputs

• Geometry Filter (optional): A table containing a single Polygon or MultiPolygon used to restrict results to chips intersecting that geometry.

Settings

• Tenant ID: Your LGND tenant identifier (ten_...).

• Collection ID: The collection to search (col_...).

• API Token: Your LGND API authentication token (sk_...).

• Chip ID: Identifier of the reference chip whose embedding will be used as the search query (chip_...).

• Top K: Number of results to return. Between 1 and 100. Default: 10.

• Start Date (optional): Only consider imagery captured on or after this date (YYYY-MM-DD).

• End Date (optional): Only consider imagery captured on or before this date (YYYY-MM-DD).

• Geometry Column (optional): Geography column in the Geometry Filter table.

Output

• Output table: The chips ranked by similarity score. Each row contains chip_id, raster_id, cell_id, datetime, score, distance, collection, centroid and geometry.

LGND Location Search

Description

Performs a similarity search using a geographic point. The component looks up the chip at the given latitude/longitude and uses its embedding to find similar chips across the collection.

Inputs

• Geometry Filter (optional): A table containing a single Polygon or MultiPolygon used to restrict results to chips intersecting that geometry.

Settings

• Tenant ID: Your LGND tenant identifier (ten_...).

• Collection ID: The collection to search (col_...).

• API Token: Your LGND API authentication token (sk_...).

• Latitude: Latitude of the reference location, between -90 and 90.

• Longitude: Longitude of the reference location, between -180 and 180.

• Top K: Number of results to return. Between 1 and 100. Default: 10.

• Start Date (optional): When resolving the reference chip, only consider imagery captured on or after this date (YYYY-MM-DD).

• End Date (optional): When resolving the reference chip, only consider imagery captured on or before this date (YYYY-MM-DD).

• Geometry Column (optional): Geography column in the Geometry Filter table.

Output

• Output table: The chips ranked by similarity score. Each row contains chip_id, raster_id, cell_id, datetime, score, distance, collection, centroid and geometry.

LGND Geometry Filter

Description

Returns all chips in the collection whose geometry intersects a provided polygon, ordered by datetime newest first. No similarity search is performed — this is a pure spatial filter, useful for browsing coverage in an area.

Inputs

• Geometry Filter: A table containing a single Polygon or MultiPolygon. Must intersect the collection's spatial bounds.

Settings

• Tenant ID: Your LGND tenant identifier (ten_...).

• Collection ID: The collection to filter (col_...).

• API Token: Your LGND API authentication token (sk_...).

• Geometry Column: Geography column in the Geometry Filter table.

• Start Date (optional): Only return chips captured on or after this date (YYYY-MM-DD).

• End Date (optional): Only return chips captured on or before this date (YYYY-MM-DD).

• Max Results: Maximum number of chips to return. Between 1 and 1000. Default: 100.

Output

• Output table: Chips intersecting the provided geometry, ordered by datetime newest first. Each row contains chip_id, cell_id, raster_id, geometry, datetime, collection and centroid.

LGND Change Detection

Description

Detects changes over time by comparing historical chips against the most recent chips within each geographic cell. For each cell, the component scores chips against a "past state" description and a "current state" description, and returns the cells where both signals are strongest — i.e. cells that used to match the past description and now match the current description.

Optional negative descriptions can be provided for either state to steer the embedding away from likely false positives.

Inputs

• Geometry Filter (optional): A table containing a single Polygon or MultiPolygon used to restrict results to chips intersecting that geometry.

Settings

• Tenant ID: Your LGND tenant identifier (ten_...).

• Collection ID: The collection to search (col_...).

• API Token: Your LGND API authentication token (sk_...).

• Past State - Positive Description (optional): Semicolon-separated descriptions of what the area looked like historically. Each term is used as a separate search signal. Example: agricultural cropland; fields.

• Past State — Negative Description (optional): Semicolon-separated descriptions of what the historical area did NOT look like, used to steer away from false positives. Example: homes; buildings; roads.

• Current State - Positive Description (optional): Semicolon-separated descriptions of what the area looks like now. Example: solar panel installation; industrial area.

• Current State — Negative Description (optional): Semicolon-separated descriptions of what the current area does NOT look like. Example: agricultural cropland; fields.

• Top K: Maximum number of changed chip pairs to return. Between 1 and 100. Default: 10.

• Geometry Column (optional): Geography column in the Geometry Filter table.

Output

• Output table: Detected change pairs, one row per geographic cell. Each row contains the shared cell_id, the combined score (higher = more change), score_past and score_current, and the past/current chip details (chip_id_past, raster_id_past, datetime_past, geometry_past, chip_id_current, raster_id_current, datetime_current, geometry_current) plus collection.

LGND Chip Thumbnail URL

Description

Adds a thumbnail URL column to any table that contains chip IDs — typically the output of one of the LGND search components. For each chip, the component fetches the authenticated LGND thumbnail image, uploads it to a GCS bucket, and returns the public URL, which can then be rendered as a tooltip or popup image in a CARTO map.

Inputs

• Input Table: A table containing a column with chip IDs.

Settings

• Chip ID Column: Column in the input table containing the chip IDs (chip_...).

• API Token: Your LGND API Bearer token used to authenticate the thumbnail requests (sk_...).

Output

• Output table: The input table with one additional column, {chip_id_column}_thumbnail_url, containing the public GCS URL of the thumbnail image for each chip.