Using the CartoLayer


The CartoLayer is a 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.

Connecting to CARTO 3

  1. 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. 2.
    Create a token using our token API with access to the required table. To make the request to the tokens endpoint, you need to get an access token first. Please read the API documentation to know how to get it.
    curl --location -g --request POST ''
    --header 'Content-Type: application/json'
    --data-raw '{
    "grants": [
    "connection_name": "bqconn",
    "source": "cartobq.public_account.populated_places"
  3. 3.
    Set connection parameters
    A function setDefaultCredentials is provided to define the connection parameters to CARTO:
    apiBaseUrl: '',
    accessToken: 'eyJhbGciOiJIUzI1NiJ9.eyJhIjoiYWNfbHFlM3p3Z3UiLCJqdGkiOiI1YjI0OWE2ZCJ9.Y7zB30NJFzq5fPv8W5nkoH5lPXFWQP0uywDtqUg8y8c'
    For more info about the parameters of this function, check the reference.
  4. 4.
    Create a layer using the previously created connection:
    new CartoLayer({
    id: 'places',
    connection: 'bqconn',
    type: MAP_TYPES.TABLE,
    data: 'cartobq.public_account.populated_places',
    pointRadiusMinPixels: 2,
    getFillColor: [200, 0, 80],
View the complete example here
If you are using CARTO 2, there are some differences you need to take into account when specifying the properties:
  • setDefaultCredentials needs an username and apiKey. For more info check the reference or our guide for Managing your API keys
  • The connection parameter is not required.
username: 'public',
apiKey: 'default_public'
new CartoLayer({
data: 'SELECT * FROM world_population_2015',
pointRadiusMinPixels: 2,
getLineColor: [0, 0, 0, 0.75],
getFillColor: [238, 77, 90],
lineWidthMinPixels: 1

Geometry column

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 is MAP_TYPES.QUERY, you need to alias the geometry column to geom
  • If the type is MAP_TYPES.TABLE, you need to specify the name of the column containing the geometry or the spatial index using the geoColumn property.

Support for other layers

The CartoLayer uses the GeoJsonLayer for rendering but you can also use any other 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 data
  • data: the actual data response
import { fetchLayerData, FORMATS } from '';
import { H3HexagonLayer } from '';
const result = await fetchLayerData({
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
connection: 'connection_name',
const data =;
new H3HexagonLayer({
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.