Integration with CARTO platform for data visualization including specialized layers, basemaps, styling functions, and seamless access to CARTO's cloud data infrastructure.
Main layer for rendering data from CARTO platform with support for SQL queries, datasets, and tilesets.
/**
* Composite layer for CARTO platform data visualization
*/
class CartoLayer extends CompositeLayer {
constructor(props: CartoLayerProps);
}
interface CartoLayerProps extends CompositeLayerProps {
/** SQL query, dataset name, or tileset name */
data: string;
/** Data type - query, table, or tileset */
type: MapType;
/** Connection name in CARTO workspace (required for API v3) */
connection?: string;
/** Override default tile data format */
formatTiles?: TileFormat;
/** Geo column name (default: 'geom') */
geoColumn?: string;
/** Columns to include in tile data */
columns?: string[];
/** CARTO API version */
apiVersion?: APIVersion;
/** CARTO credentials */
credentials?: Credentials;
/** Query parameters for filtering data */
queryParameters?: QueryParameters;
/** Callback for successful data loading */
onDataLoad?: (data: any) => void;
/** Callback for data loading errors */
onDataError?: (error: CartoAPIError) => void;
/** Unique ID property name */
uniqueIdProperty?: string;
}
type MapType = 'query' | 'table' | 'tileset';
type TileFormat = 'binary' | 'geojson' | 'mvt';
type APIVersion = 'v1' | 'v2' | 'v3';
interface Credentials {
apiKey?: string;
username?: string;
apiBaseUrl?: string;
accessToken?: string;
region?: string;
}
interface QueryParameters {
[key: string]: string | number | boolean;
}Usage Examples:
import {CartoLayer} from '@deck.gl/carto';
// SQL query layer
const queryLayer = new CartoLayer({
id: 'carto-sql',
data: 'SELECT * FROM world_population WHERE pop_est > 1000000',
type: 'query',
connection: 'carto_dw',
apiVersion: 'v3',
getFillColor: [200, 100, 80, 180],
pickable: true
});
// Table layer with styling
const tableLayer = new CartoLayer({
id: 'carto-table',
data: 'nyc_taxi_trips',
type: 'table',
connection: 'my_connection',
geoColumn: 'pickup_geom',
columns: ['trip_distance', 'fare_amount'],
onDataLoad: data => console.log('Loaded:', data),
getFillColor: d => [d.properties.fare_amount * 10, 100, 100]
});
// Tileset layer
const tilesetLayer = new CartoLayer({
id: 'carto-tileset',
data: 'public.world_borders',
type: 'tileset',
getFillColor: [100, 200, 100, 100],
getLineColor: [255, 255, 255],
lineWidthMinPixels: 1
});Functions for managing CARTO platform credentials.
/**
* Set default credentials for CARTO layers
*/
function setDefaultCredentials(credentials: Credentials): void;
/**
* Get current default credentials
*/
function getDefaultCredentials(): Credentials;
interface Credentials {
/** API key for authentication */
apiKey?: string;
/** Username for legacy authentication */
username?: string;
/** Base URL for CARTO API */
apiBaseUrl?: string;
/** Access token for OAuth authentication */
accessToken?: string;
/** CARTO cloud region */
region?: 'us' | 'eu' | string;
}Usage Examples:
import {setDefaultCredentials, getDefaultCredentials} from '@deck.gl/carto';
// Set credentials once for all layers
setDefaultCredentials({
apiKey: 'your-api-key',
username: 'your-username',
region: 'us'
});
// Or use access token for OAuth
setDefaultCredentials({
accessToken: 'your-access-token',
apiBaseUrl: 'https://gcp-us-east1.api.carto.com'
});Color styling functions with CARTO palettes and data-driven styling support.
/**
* Create color bins styling function
*/
function colorBins<DataT = any>(options: ColorBinsOptions<DataT>): AccessorFunction<DataT, Color>;
interface ColorBinsOptions<DataT> {
/** Attribute selector for binning */
attr: AttributeSelector<DataT, number>;
/** Bin boundaries */
domain: number[];
/** Colors for each bin */
colors?: Color[] | string;
/** Color for null values */
nullColor?: Color;
}
/**
* Create categorical color styling function
*/
function colorCategories<DataT = any>(options: ColorCategoriesOptions<DataT>): AccessorFunction<DataT, Color>;
interface ColorCategoriesOptions<DataT> {
/** Attribute selector for categories */
attr: AttributeSelector<DataT, string | number>;
/** Category values */
domain: (string | number)[];
/** Colors for each category */
colors?: Color[] | string;
/** Color for null values */
nullColor?: Color;
/** Color for values not in domain */
othersColor?: Color;
}
/**
* Create continuous color styling function
*/
function colorContinuous<DataT = any>(options: ColorContinuousOptions<DataT>): AccessorFunction<DataT, Color>;
interface ColorContinuousOptions<DataT> {
/** Attribute selector for continuous values */
attr: AttributeSelector<DataT, number>;
/** Value range [min, max] */
domain: [number, number];
/** Color range or palette name */
colors?: Color[] | string;
/** Color for null values */
nullColor?: Color;
}
type AttributeSelector<DataT, ValueT> =
| string
| ((d: DataT) => ValueT);
type Color = [number, number, number] | [number, number, number, number];Usage Examples:
import {CartoLayer, colorBins, colorCategories, colorContinuous} from '@deck.gl/carto';
// Color bins styling
const layer1 = new CartoLayer({
id: 'population',
data: 'SELECT * FROM world_countries',
type: 'query',
getFillColor: colorBins({
attr: 'pop_est',
domain: [0, 100000, 1000000, 10000000, 100000000],
colors: 'BluYl'
})
});
// Categorical styling
const layer2 = new CartoLayer({
id: 'regions',
data: 'SELECT * FROM world_regions',
type: 'query',
getFillColor: colorCategories({
attr: 'region',
domain: ['Europe', 'Asia', 'Africa', 'Americas', 'Oceania'],
colors: 'Prism'
})
});
// Continuous styling
const layer3 = new CartoLayer({
id: 'temperature',
data: 'SELECT * FROM weather_stations',
type: 'query',
getFillColor: colorContinuous({
attr: 'temperature',
domain: [-20, 40],
colors: ['blue', 'white', 'red']
})
});Predefined basemap configurations for CARTO visualizations.
/**
* CARTO basemap configurations
*/
const BASEMAP: {
POSITRON: string;
VOYAGER: string;
DARK_MATTER: string;
GOOGLE_ROADMAPS: string;
GOOGLE_SATELLITE: string;
GOOGLE_HYBRID: string;
};Usage Examples:
import {BASEMAP} from '@deck.gl/carto';
import {Deck, MapView} from 'deck.gl';
const deck = new Deck({
views: new MapView(),
initialViewState: {
longitude: -74,
latitude: 40.7,
zoom: 11
},
map: {
mapStyle: BASEMAP.POSITRON
},
layers: [
// Your CARTO layers
]
});Direct API access functions for advanced use cases.
/**
* Fetch layer data from CARTO platform
*/
function fetchLayerData(props: {
data: string;
type: MapType;
connection?: string;
credentials?: Credentials;
queryParameters?: QueryParameters;
}): Promise<any>;
/**
* Fetch map configuration from CARTO
*/
function fetchMap(props: {
cartoMapId: string;
credentials?: Credentials;
}): Promise<any>;
/**
* CARTO API error class
*/
class CartoAPIError extends Error {
type: string;
message: string;
responseStatus?: number;
context?: any;
}interface FetchLayerDataResult {
data: any[];
meta: {
stats: {
[column: string]: ColumnStats;
};
tilestats: any;
};
}
interface ColumnStats {
min?: number;
max?: number;
avg?: number;
sum?: number;
count?: number;
categories?: Array<{category: string | number; frequency: number}>;
}
interface APIErrorContext {
requestId?: string;
endpoint?: string;
method?: string;
statusCode?: number;
}
// Constants
const MAP_TYPES: {
QUERY: 'query';
TABLE: 'table';
TILESET: 'tileset';
};
const TILE_FORMATS: {
BINARY: 'binary';
GEOJSON: 'geojson';
MVT: 'mvt';
};
const API_VERSIONS: {
V1: 'v1';
V2: 'v2';
V3: 'v3';
};