API

View on Github

Package	Version	Downloads
@carto/react-api

Set of functions that allow to work with CARTO APIs.

Functions

executeSQL

Async function that executes a SQL query against CARTO SQL API

• Input:

  Receives a single Object argument with the following properties:

Param	Type	Description
credentials	Object	CARTO user credentials (check the parameters here)
credentials.apiVersion	string	SQL API version
credentials.username	string	CARTO username (required for CARTO 2)
credentials.apiKey	string	CARTO API Key (required for CARTO 2)
credentials.apiBaseUrl	string	API Base URL (required for CARTO 3)
credentials.accessToken	string	Access token (required for CARTO 3)
query	string	SQL query to be executed
connection	string	Connection name (required for CARTO 3)
opts	Object	Optional. Additional options for the HTTP request, following the Request interface
opts.abortController	AbortController	To cancel the network request using AbortController
opts.format	string	Output format to be passed to SQL API (i.e. ‘geojson’)
queryParameters	QueryParameters (@deck.gl/carto)	Optional. SQL query parameters

• Returns: Object - Data returned from the SQL query execution

• Example:

import { executeSQL } from "@carto/react-api";

const credentials = {
  username: "public",
  apiKey: "default_public"
};
const query = `SELECT COUNT(cartodb_id) FROM populated_places`;

const fetchData = async () => {
  const result = await executeSQL({credentials, query});
  return result;
};

const rows = await fetchData();
console.log(rows[0]); // {count: 7343}

useCartoLayerProps

React hook that allows a more powerful use of CARTO deck.gl layers, creating a set of layer props (see @deck.gl/carto module). It manages automatically filtering and viewport-related calculations, for common use cases.

• Input:

Param	Type	Default	Description
props	Object		{ source, [layerConfig], [uniqueIdProperty], [viewportFeatures], [viewportFeaturesDebounceTimeout]}
props.source	Object		{ id, type, connection, data, [credentials] }
props.source.id	string		Unique source ID.
props.source.type	string		Source type. Check available types here
props.source.connection	string		Connection name. Required only for CARTO 3.
props.source.data	string		Table name, tileset name or SQL query.
props.source.queryParameters	QueryParameters (@deck.gl/carto)		SQL query parameters
[props.source.credentials]	object		(optional) Credentials for accessing the source (check the object props here).
[props.layerConfig]	Object		(optional) { id, opacity, visible }
[props.layerConfig.id]	string		(optional) Unique layer ID.
[props.layerConfig.opacity]	number	1	(optional) Initial layer opacity.
[props.layerConfig.visible]	boolean	true	(optional) Indicates whether the layer is visible by default or not.
[props.uniqueIdProperty]	string		(optional) Name of the column for identifying features uniquely. See note below.
[props.viewportFeatures]	boolean	true	(optional) Whether to calculate viewport features for this layer or not.
[props.viewportFeaturesDebounceTimeout]	number	250	(optional) Timeout for calculating viewport features when there’s a change. It’s used to avoid repeated viewport calculations in a short amount of time.

About uniqueIdProperty: the uniqueIdProperty allows to identify a feature uniquely. When using tiles, it allows to detect portions of a same feature present in different tiles (think about a road segment crossing 2 tiles) and apply correct calculations (eg. avoid counting the same feature more than once). These are the rules used internally, in this precise order:

1. if user indicates a particular property, it will be honoured.

2. if cartodb_id is present, it will be used (all features coming from a CartoLayer with Maps API version v2 have this field, just be sure to include it in the SQL you use)

3. if geoid is present, it will be used. Some datasets with MAP_TYPES.TILESET type have this identifier.

4. finally, if a value isn’t set for this param and none cartodb_id or geoid are found, every feature (or portion of a feature), will be treated as a unique feature.

• Returns: a set of props for the layer.

Param	Type	Description
props	Object	Default props required for layers
props.binary	boolean	Returns true. The internal viewportFeatures calculation requires MVT property set to true
props.uniqueIdProperty	string	Returns same unique id property for the layer as the input one
props.type	string	Source type. Check available types here
props.connection	string	Connection name. Used only for CARTO 3.
props.data	string	Table name, tileset name or SQL query
props.credentials	string	Credentials for accessing the source
props.onViewportLoad	function	Function that is called when all tiles in the current viewport are loaded. Available when using vector tile sources. Vector tiles are returned if using Maps API v2, or if using Maps API v3 with MAP_TYPES.TILESET sources.
props.onDataLoad	function	Function that is called when all the dataset features are loaded. Available when using Maps API v3 with MAP_TYPES.TABLE or MAP_TYPES.QUERY sources.
props.getFilterValue	function	Accessor to the filterable value of each data object
props.filterRange	[number, number]	The [min, max] bounds of the filter values to display
props.extensions	[Object]	Bonus features to add to the core deck.gl layers
props.updateTriggers	Object	Tells deck.gl exactly which attributes need to change, and when
props.updateTriggers.getFilterValue	Object	Updating getFilterValue accessor when new filters are applied to source

• Example

import { useCartoLayerProps } from '@carto/react-api';

const cartoLayerProps = useCartoLayerProps(source);

const layer = new CartoLayer({
  ...cartoLayerProps,
  id: 'exampleLayer',
  getFillColor: [255, 0, 255],
}