CARTO for React

CARTO for React

Github Code

API

Package Version Downloads
@carto/react-api version downloads

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’)

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

  • Example:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

    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.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.
  • 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:

    1
2
3
4
5
6
7
8
9

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

const cartoLayerProps = useCartoLayerProps(source);

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