Specialized integration for CARTO platform with purpose-built layers and data source connectors for geospatial analytics and visualization of large-scale location data.
Purpose-built layers optimized for CARTO's data platform and analytics workflows.
Renders CARTO vector tile data with built-in styling and interactivity.
/**
* Vector tile layer for CARTO data
* Optimized for rendering large vector datasets from CARTO tiles
*/
class VectorTileLayer extends Layer {
constructor(props: VectorTileLayerProps);
}
interface VectorTileLayerProps extends LayerProps {
/** Vector tile data source */
data: string | TilejsonResult;
/** Tile size in pixels */
tileSize?: number;
/** Maximum zoom level */
maxZoom?: number;
/** Minimum zoom level */
minZoom?: number;
/** Feature filter function */
filterFeatures?: (feature: any) => boolean;
/** Unique ID accessor */
uniqueIdProperty?: string;
/** Highlight color for selected features */
highlightColor?: Color;
/** Auto-highlight on hover */
autoHighlight?: boolean;
/** Function to get fill color */
getFillColor?: AccessorFunction<any, Color>;
/** Function to get line color */
getLineColor?: AccessorFunction<any, Color>;
/** Function to get line width */
getLineWidth?: AccessorFunction<any, number>;
/** Function to get point radius */
getPointRadius?: AccessorFunction<any, number>;
/** Enable filled polygons */
filled?: boolean;
/** Enable stroked outlines */
stroked?: boolean;
}Renders H3 hexagonal tile data from CARTO with aggregation support.
/**
* H3 tile layer for CARTO H3 data
* Renders hexagonal binned data with aggregation
*/
class H3TileLayer extends Layer {
constructor(props: H3TileLayerProps);
}
interface H3TileLayerProps extends LayerProps {
/** H3 tile data source */
data: string | TilejsonResult;
/** Function to get hexagon fill color */
getFillColor?: AccessorFunction<any, Color>;
/** Function to get elevation for 3D hexagons */
getElevation?: AccessorFunction<any, number>;
/** Enable 3D extrusion */
extruded?: boolean;
/** Coverage factor (0-1) */
coverage?: number;
/** Elevation scale multiplier */
elevationScale?: number;
/** Upper percentile for auto-scaling */
upperPercentile?: number;
/** Lower percentile for auto-scaling */
lowerPercentile?: number;
/** Material for 3D rendering */
material?: Material;
}Renders clustered point data from CARTO with dynamic aggregation.
/**
* Cluster tile layer for CARTO clustered data
* Renders point clusters with size-based styling
*/
class ClusterTileLayer extends Layer {
constructor(props: ClusterTileLayerProps);
}
interface ClusterTileLayerProps extends LayerProps {
/** Cluster tile data source */
data: string | TilejsonResult;
/** Function to get cluster position */
getPosition?: AccessorFunction<any, Position>;
/** Function to get cluster radius */
getRadius?: AccessorFunction<any, number>;
/** Function to get cluster color */
getFillColor?: AccessorFunction<any, Color>;
/** Radius scale multiplier */
radiusScale?: number;
/** Minimum radius in pixels */
radiusMinPixels?: number;
/** Maximum radius in pixels */
radiusMaxPixels?: number;
/** Units for radius */
radiusUnits?: Unit;
}Renders heatmap visualization from CARTO tile data.
/**
* Heatmap tile layer for CARTO density data
* Creates smooth heatmap visualizations from tiled data
*/
class HeatmapTileLayer extends Layer {
constructor(props: HeatmapTileLayerProps);
}
interface HeatmapTileLayerProps extends LayerProps {
/** Heatmap tile data source */
data: string | TilejsonResult;
/** Function to get data point position */
getPosition?: AccessorFunction<any, Position>;
/** Function to get weight/intensity */
getWeight?: AccessorFunction<any, number>;
/** Heatmap radius in pixels */
radius?: number;
/** Intensity multiplier */
intensity?: number;
/** Intensity threshold */
threshold?: number;
/** Color range for heatmap */
colorRange?: Color[];
/** Aggregation method */
aggregation?: 'SUM' | 'MEAN';
}Renders raster/image tile data from CARTO.
/**
* Raster tile layer for CARTO raster data
* Displays tiled raster imagery and analysis results
*/
class RasterTileLayer extends Layer {
constructor(props: RasterTileLayerProps);
}
interface RasterTileLayerProps extends LayerProps {
/** Raster tile data source */
data: string | TilejsonResult;
/** Tile size in pixels */
tileSize?: number;
/** Maximum zoom level */
maxZoom?: number;
/** Minimum zoom level */
minZoom?: number;
/** Transparent color value */
transparentColor?: Color;
/** Tint color overlay */
tintColor?: Color;
/** Desaturation amount (0-1) */
desaturate?: number;
}Functions for connecting to CARTO's data platform and APIs.
Access CARTO tables directly:
/**
* Create vector data source from CARTO table
*/
function vectorTableSource(options: VectorTableSourceOptions): Promise<TilejsonResult>;
/**
* Create H3 data source from CARTO table
*/
function h3TableSource(options: H3TableSourceOptions): Promise<TilejsonResult>;
/**
* Create boundary data source from CARTO table
*/
function boundaryTableSource(options: BoundaryTableSourceOptions): Promise<TilejsonResult>;
/**
* Create quadbin data source from CARTO table
*/
function quadbinTableSource(options: QuadbinTableSourceOptions): Promise<TilejsonResult>;
interface VectorTableSourceOptions extends TableSourceOptions {
/** Aggregation columns */
columns?: {[key: string]: string};
/** Spatial resolution for clustering */
spatialDataColumn?: string;
/** Spatial data type */
spatialDataType?: 'geo' | 'h3' | 'quadbin';
}
interface TableSourceOptions extends SourceOptions {
/** Table name in CARTO */
tableName: string;
/** Optional schema name */
schemaName?: string;
}Execute SQL queries against CARTO:
/**
* Create vector data source from CARTO SQL query
*/
function vectorQuerySource(options: VectorQuerySourceOptions): Promise<TilejsonResult>;
/**
* Create H3 data source from CARTO SQL query
*/
function h3QuerySource(options: H3QuerySourceOptions): Promise<TilejsonResult>;
/**
* Execute arbitrary SQL query
*/
function query(options: QueryOptions): Promise<QueryResult>;
interface VectorQuerySourceOptions extends QuerySourceOptions {
/** Aggregation columns */
columns?: {[key: string]: string};
/** Spatial column name */
spatialDataColumn?: string;
}
interface QuerySourceOptions extends SourceOptions {
/** SQL query string */
sqlQuery: string;
/** Query parameters */
queryParameters?: {[key: string]: any};
}
interface QueryOptions {
/** SQL query string */
query: string;
/** Connection parameters */
connectionName?: string;
/** Query timeout */
timeout?: number;
}Access pre-built CARTO tilesets:
/**
* Create vector data source from CARTO tileset
*/
function vectorTilesetSource(options: VectorTilesetSourceOptions): Promise<TilejsonResult>;
/**
* Create H3 data source from CARTO tileset
*/
function h3TilesetSource(options: H3TilesetSourceOptions): Promise<TilejsonResult>;
interface TilesetSourceOptions extends SourceOptions {
/** Tileset name */
tableName: string;
}Color and styling functions for CARTO visualizations.
/**
* Create color bins for categorical data
*/
function colorBins(options: ColorBinsOptions): ColorBinsResult;
/**
* Create color categories for discrete data
*/
function colorCategories(options: ColorCategoriesOptions): ColorCategoriesResult;
/**
* Create continuous color scale
*/
function colorContinuous(options: ColorContinuousOptions): ColorContinuousResult;
interface ColorBinsOptions {
/** Attribute to bin */
attribute: string;
/** Number of bins */
bins: number;
/** Color palette */
palette?: string | Color[];
/** Bin method */
method?: 'quantiles' | 'equal' | 'stdev';
}
interface ColorCategoriesOptions {
/** Attribute to categorize */
attribute: string;
/** Maximum categories */
maxCategories?: number;
/** Color palette */
palette?: string | Color[];
/** Default color for uncategorized */
defaultColor?: Color;
}
interface ColorContinuousOptions {
/** Attribute for continuous scale */
attribute: string;
/** Color range */
range: Color[];
/** Value domain */
domain?: [number, number];
}Access CARTO's basemap styles and configuration.
/**
* CARTO basemap configurations
*/
const BASEMAP: {
POSITRON: string;
VOYAGER: string;
DARK_MATTER: string;
};
/**
* Fetch basemap properties for map integration
*/
function fetchBasemapProps(options: BasemapOptions): Promise<BasemapResult>;
interface BasemapOptions {
/** Basemap style name */
basemap: string;
/** Custom style parameters */
parameters?: {[key: string]: any};
}import { VectorTileLayer, vectorTableSource } from '@deck.gl/carto';
// Create data source
const dataSource = await vectorTableSource({
connectionName: 'carto_dw',
tableName: 'cartobq.public_account.world_population',
columns: {
population: 'SUM(population)',
area: 'SUM(area_km2)'
},
spatialDataColumn: 'geom'
});
// Create layer
const layer = new VectorTileLayer({
id: 'population',
data: dataSource,
getFillColor: d => {
const density = d.properties.population / d.properties.area;
return density > 100 ? [255, 0, 0] : [0, 255, 0];
},
getLineColor: [255, 255, 255],
lineWidthMinPixels: 1,
filled: true,
stroked: true,
pickable: true
});import { H3TileLayer, h3QuerySource } from '@deck.gl/carto';
// Query with H3 aggregation
const h3Data = await h3QuerySource({
sqlQuery: `
SELECT
h3_compact(ARRAY_AGG(h3)) as h3,
SUM(value) as total_value,
AVG(metric) as avg_metric
FROM my_table
WHERE ST_DWithin(geom, ST_Point(-74.0, 40.7), 50000)
GROUP BY h3_parent(h3, 7)
`,
spatialDataColumn: 'h3'
});
const h3Layer = new H3TileLayer({
id: 'h3-aggregation',
data: h3Data,
getFillColor: d => {
const value = d.properties.total_value;
if (value > 1000) return [255, 0, 0];
if (value > 100) return [255, 165, 0];
return [255, 255, 0];
},
getElevation: d => d.properties.avg_metric * 100,
extruded: true,
coverage: 0.8
});import {
VectorTileLayer,
vectorTableSource,
colorBins
} from '@deck.gl/carto';
// Create styled layer with CARTO color utilities
const colorMapping = colorBins({
attribute: 'revenue',
bins: 7,
method: 'quantiles',
palette: 'SunsetDark'
});
const styledLayer = new VectorTileLayer({
id: 'revenue-choropleth',
data: await vectorTableSource({
connectionName: 'carto_dw',
tableName: 'retail_locations',
columns: {
revenue: 'SUM(monthly_revenue)',
store_count: 'COUNT(*)'
}
}),
getFillColor: d => {
const revenue = d.properties.revenue;
return colorMapping.getColor(revenue);
},
filled: true,
pickable: true
});import { ClusterTileLayer, vectorQuerySource } from '@deck.gl/carto';
class RealtimeCartoLayer {
private layer: ClusterTileLayer;
private refreshInterval: number;
constructor() {
this.refreshInterval = 30000; // 30 seconds
this.createLayer();
this.startAutoRefresh();
}
private async createLayer() {
const data = await vectorQuerySource({
sqlQuery: `
SELECT * FROM realtime_events
WHERE event_time > NOW() - INTERVAL 1 HOUR
`,
spatialDataColumn: 'location'
});
this.layer = new ClusterTileLayer({
id: 'realtime-events',
data,
getRadius: d => Math.sqrt(d.properties.event_count) * 20,
getFillColor: d => {
const recency = Date.now() - new Date(d.properties.latest_event).getTime();
const hours = recency / (1000 * 60 * 60);
if (hours < 0.5) return [255, 0, 0]; // Very recent - red
if (hours < 2) return [255, 165, 0]; // Recent - orange
return [255, 255, 0]; // Older - yellow
},
radiusMinPixels: 10,
radiusMaxPixels: 100,
pickable: true
});
}
private startAutoRefresh() {
setInterval(() => {
this.createLayer();
}, this.refreshInterval);
}
}Combine multiple CARTO data sources:
import {
VectorTileLayer,
H3TileLayer,
ClusterTileLayer,
vectorTableSource,
h3QuerySource,
vectorQuerySource
} from '@deck.gl/carto';
// Base layer: Administrative boundaries
const boundariesLayer = new VectorTileLayer({
id: 'boundaries',
data: await vectorTableSource({
tableName: 'administrative_boundaries',
columns: { name: 'region_name', population: 'SUM(population)' }
}),
getFillColor: [240, 240, 240, 100],
getLineColor: [128, 128, 128],
stroked: true,
filled: true
});
// Aggregation layer: H3 density analysis
const densityLayer = new H3TileLayer({
id: 'population-density',
data: await h3QuerySource({
sqlQuery: 'SELECT h3, SUM(population) as pop FROM census_h3 GROUP BY h3'
}),
getFillColor: d => densityColorScale(d.properties.pop),
extruded: true,
coverage: 0.6
});
// Point layer: Real-time events
const eventsLayer = new ClusterTileLayer({
id: 'events',
data: await vectorQuerySource({
sqlQuery: 'SELECT * FROM events WHERE created_at > CURRENT_TIMESTAMP - INTERVAL 1 DAY'
}),
getFillColor: [255, 100, 0],
getRadius: 50
});
const layers = [boundariesLayer, densityLayer, eventsLayer];import { CartoAPIError, vectorTableSource } from '@deck.gl/carto';
async function createCartoLayer(tableConfig) {
try {
const dataSource = await vectorTableSource(tableConfig);
return new VectorTileLayer({
id: 'carto-layer',
data: dataSource,
// ... layer props
});
} catch (error) {
if (error instanceof CartoAPIError) {
console.error('CARTO API Error:', error.message);
// Handle specific error codes
switch (error.statusCode) {
case 401:
throw new Error('Authentication failed. Check your API key.');
case 403:
throw new Error('Access denied. Check table permissions.');
case 404:
throw new Error('Table not found. Verify table name.');
default:
throw new Error(`CARTO API error: ${error.message}`);
}
}
// Fallback to static data
console.warn('Falling back to static data due to CARTO error');
return createFallbackLayer();
}
}