CartoLayer
is the layer to visualize data using the CARTO Maps API.
By default the CartoLayer
expects the data to be described using longitude & latitude. Tiled data will be used, with the format depending on formatTiles
.
A MVTLayer
will be created and all properties will be inherited.
import DeckGL from '@deck.gl/react';
import {CartoLayer, setDefaultCredentials, MAP_TYPES, API_VERSIONS} from '@deck.gl/carto';
setDefaultCredentials({
accessToken: 'XXX'
apiBaseUrl: 'https://gcp-us-east1.api.carto.com' // Default value (optional)
});
function App({viewState}) {
const layer = new CartoLayer({
type: MAP_TYPES.QUERY,
connection: 'bigquery',
data: 'SELECT * FROM cartobq.testtables.points_10k',
pointRadiusMinPixels: 2,
getLineColor: [0, 0, 0, 200],
getFillColor: [238, 77, 90],
lineWidthMinPixels: 1
})
return <DeckGL viewState={viewState} layers={[layer]} />;
}
The CARTO platform supports storing data using a spatial index. The geoColumn
prop is used to specify a database column that contains geographic data. When geoColumn
has one of the following values, the data will be interpreted as a spatial index:
Tiled data will be used, with the layer created depending on the spatial index used:
h3
H3HexagonLayer
will be created and all properties will be inherited.quadbin
QuadkeyLayer
will be created and all properties will be inherited. Note the getQuadkey
accessor is replaced with getQuadbin
.import DeckGL from '@deck.gl/react';
import {CartoLayer, setDefaultCredentials, MAP_TYPES, API_VERSIONS} from '@deck.gl/carto';
setDefaultCredentials({
accessToken: 'XXX'
apiBaseUrl: 'https://gcp-us-east1.api.carto.com' // Default value (optional)
});
function App({viewState}) {
const layer = new CartoLayer({
type: MAP_TYPES.TABLE,
connection: 'bigquery',
data: 'cartobq.testtables.h3',
geoColumn: 'h3',
aggregationExp: 'AVG(population) as population',
getFillColor: [238, 77, 90],
getElevation: d => d.properties.population
})
return <DeckGL viewState={viewState} layers={[layer]} />;
}
To install the dependencies from NPM:
npm install deck.gl
# or
npm install @deck.gl/core @deck.gl/layers @deck.gl/carto
import {CartoLayer} from '@deck.gl/carto';
new CartoLayer({});
To use pre-bundled scripts:
<script src="https://unpkg.com/deck.gl@^8.7.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/carto@^8.7.0/dist.min.js"></script>
<!-- or -->
<script src="https://unpkg.com/@deck.gl/core@^8.7.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/layers@^8.7.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/geo-layers@^8.7.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/carto@^8.7.0/dist.min.js"></script>
new deck.carto.CartoLayer({});
In all cases the properties of TileLayer
will be inherited.
Depending on the datasource, additional properties will be inherited from the created sublayer:
h3
spatial index: H3HexagonLayer
.quadbin
spatial index: QuadkeyLayer
. Note the getQuadkey
accessor is replaced with getQuadbin
.MVTLayer
.data
(String)Required. Either a SQL query or a name of dataset/tileset.
type
(String)Required. Data type. Possible values are:
MAP_TYPES.QUERY
, if data
is a SQL query.MAP_TYPES.TILESET
, if data
is a tileset name.MAP_TYPES.TABLE
, if data
is a dataset name. Only supported with API v3.connection
(String, optional)Required when apiVersion
is API_VERSIONS.V3
.
Name of the connection registered in the CARTO workspace.
formatTiles
(String, optional)Only supported when apiVersion
is API_VERSIONS.V3
and format
is FORMATS.TILEJSON
. Use to override the default tile data format. Possible values are: TILE_FORMATS.BINARY
, TILE_FORMATS.GEOJSON
and TILE_FORMATS.MVT
.
geoColumn
(String, optional)Only supported when type
is MAP_TYPES.TABLE
.
Name of the geo_column
in the CARTO platform. Use this override the default column ('geom'), from which the geometry information should be fetched.
columns
(Array, optional)Only supported when type
is MAP_TYPES.TABLE
.
Names of columns to fetch. By default, all columns are fetched.
uniqueIdProperty
(String)cartodb_id
Optional. A string pointing to a unique attribute at the result of the query. A unique attribute is needed for highlighting with vector tiles when a feature is split across two or more tiles.
credentials
(Object)Optional. Overrides the configuration to connect with CARTO. Check the parameters here.
aggregationExp
(String, optional)Optional. Aggregation SQL expression. Only used for spatial index datasets.
aggregationResLevel
(Number, optional)Optional. Aggregation resolution level. Only used for spatial index datasets, defaults to 6 for quadbins, 4 for h3.
queryParameters
(Depends on provider)Optional. Use it to parametrize SQL queries. The format depends on the source's provider, some examples:
const layer = new CartoLayer({
data: `select * from users where username=$1`
queryParameters: ['alasarr']
})
const layer = new CartoLayer({
data: `select * from users where username=?`,
queryParameters: ['alasarr']
})
const layer = new CartoLayer({
data: `select * from users where username=@username`,
queryParameters: { username: 'alasarr' }
})
const layer = new CartoLayer({
data: `select * from users where username=?`,
queryParameters: ['alasarr']
})
or
const layer = new CartoLayer({
data: `select * from users where username=:1`,
queryParameters: ['alasarr']
})
const layer = new CartoLayer({
data: `select * from users where username=?`,
queryParameters: ['alasarr']
})
onDataLoad
(Function, optional)onDataLoad
is called when the request to the CARTO Maps API was completed successfully.
data => {}
Receives arguments:
data
(Object) - Data received from CARTO Maps APIonDataError
(Function, optional)onDataError
is called when the request to the CARTO Maps API failed. By default the Error is thrown.
null
Receives arguments:
error
(Error
)