Using the CartoLayer
The CartoLayer is a deck.gl
CompositeLayer
used to visualize geospatial data from the CARTO platform.It is compatible with the different versions of the CARTO Maps API (v1, v2, and v3) and is responsible for connecting to the platform in order to retrieve the data for visualization.
- 1.Go to the Workspace and create a new connection: Tip:
carto_dw
connection is also available for users who don’t have a data warehouse. - 2.Create an API Access Token using that connection. Learn how to create API Access Tokens using CARTO Workspace:
- Make sure at least Maps API is enabled,
- Add grants as needed for your application.
- 3.Copy the token and paste it into your deck.gl application. A function
setDefaultCredentials
is provided to define the connection parameters to CARTO:setDefaultCredentials({apiBaseUrl: 'https://gcp-us-east1.api.carto.com',accessToken: 'eyJhbGciOiJIUzI1NiJ9.eyJhIjoiYWNfbHFlM3p3Z3UiLCJqdGkiOiI1YjI0OWE2ZCJ9.Y7zB30NJFzq5fPv8W5nkoH5lPXFWQP0uywDtqUg8y8c'}); - 4.Create a layer using the previously created connection:new CartoLayer({id: 'places',connection: 'carto_dw',type: MAP_TYPES.QUERY,data: "SELECT geom, name FROM `carto-demo-data.demo_tables.populated_places`",pointRadiusMinPixels: 2,getFillColor: [200, 0, 80],}),
If you are using CARTO 2, there are some differences you need to take into account when specifying the properties:
- setDefaultCredentials needs an
username
andapiKey
. For more info check the reference or our guide for Managing your API keys - The
connection
parameter is not required.
setDefaultCredentials({
username: 'public',
apiKey: 'default_public'
});
new CartoLayer({
type: MAP_TYPES.QUERY,
data: 'SELECT * FROM world_population_2015',
pointRadiusMinPixels: 2,
getLineColor: [0, 0, 0, 0.75],
getFillColor: [238, 77, 90],
lineWidthMinPixels: 1
});
By default, the data source you specify in the
data
property must contain a column named “geom” with the geometry. If the column containing the geometry has a different name or you are using spatial indices instead of regular geometries, you can still use it but you need to do the following:- If the
type
isMAP_TYPES.QUERY
, you need to alias the geometry column togeom
- If the
type
isMAP_TYPES.TABLE
, you need to specify the name of the column containing the geometry or the spatial index using thegeoColumn
property.
The
CartoLayer
uses the GeoJsonLayer
for rendering but you can also use any other deck.gl layer for rendering using the fetchLayerData
function from the CARTO module.This function receives an object with the following properties:
If the format is not explicitly specified,
fetchLayerData
will pick a format automatically, depending on what is available from the CARTO API. The fetchLayerData
function returns an Object
with the following properties:format
: the format of the returned datadata
: the actual data response
import { fetchLayerData, FORMATS } from '@deck.gl/carto';
import { H3HexagonLayer } from '@deck.gl/geo-layers/';
const result = await fetchLayerData({
type: MAP_TYPES.QUERY,
source: `SELECT `carto-un`.h3.ST_ASH3(internal_point_geom, 4) as h3, count(*) as count
FROM bigquery-public-data.geo_us_census_places.us_national_places
GROUP BY h3`,
connection: 'connection_name',
format: FORMATS.JSON
});
const data = result.data;
new H3HexagonLayer({
data,
filled: true,
getHexagon: d => d.h3,
getFillColor: d => [0, (1 - d.count / 10) * 255, 0],
getLineColor: [0, 0, 0, 200],
});
If you are using CARTO 2, there isn’t an equivalent function to the
fetchLayerData
function but you can use the SQL API to retrieve the data in JSON or GeoJSON format depending on the layer you want to use. Please check the ArcLayer
example to see how it works.Last modified 1mo ago