Data Sources

A data source in CARTO for Developers defines the data that will be accessed by your application, the credentials (connection) that will be used to retrieve it, and additional parameters to control the data fetching process.

Overview

Data sources are typically imported from @carto/api-client . For example, this data source will be used to fetch a table from your data warehouse using the connection carto_dw .

import {vectorTableSource} from '@carto/api-client'

const data = vectorTableSource({
  accessToken: 'XXX',
  connectionName: 'carto_dw',
  tableName: 'carto-demo-data.demo_tables.chicago_crime_sample'
});

After initializing a source, you can reference them in your Layers and Widgets.

Source base properties

All data source take the following global options:

type SourceOptions = {
  accessToken: string;
  connectionName: string;
  apiBaseUrl?: string;
  clientId?: string;
  headers?: Record<string, string>;
};

• accessToken: The API Access Token or OAuth Access Token that will be used to fetch the data. Learn more about access tokens in Authentication methods.
• connectionName: The name of the connection in CARTO that will be used to fetch the data. Keep in mind that privileges to the data are granted via the credentials used in the connection. Learn more about connections.
• apiBaseUrl (optional): The base URL that hosts the APIs. It varies depending on your CARTO region/deployment method. By default it will use https://gcp-us-east1.api.carto.com which is the URL for the CARTO cloud US-based tenant, but it will be different if you operate in another region or in your own deployment. Learn how to obtain your API Base URL.
• clientId (optional): An arbitrary string that can be used to identify the application, area or functionality that is performing the requests. It will be reflected later in the CARTO Activity Data, allowing developers to track usage in their applications.
• headers (optional): An array of valid HTTP headers that will be attached to all requests originating from this source. This is useful to control the cache in your sources.

List of available data sources

Vector data: points, lines or polygons.

• vectorTableSource
• vectorQuerySource
• vectorTilesetSource

Spatial index data: data aggregated in H3 or Quadbin spatial indexes.

• h3TableSource
• h3QuerySource
• h3TilesetSource
• quadbinTableSource
• quadbinQuerySource
• quadbinTilesetSource

Raster data: pixels covering a specific area.

• rasterSource

Boundaries data: properties (point-based vector data) aggregated in a set of static boundaries (polygons).

• boundaryTableSource
• boundaryQuerySource

Using data sources

Data sources return a JavaScript Promise — You as a developer in most cases do not need to worry about the lifecycle of a data source. Instead, simply plug your data source into a CARTO tile layer from the @deck.gl/CARTO module or into a CARTO widget.

Additional information can be found inside each specific source documentation, and we have prepared a full set of working examples