# @carto/api-client > Client library for CARTO APIs and framework-agnostic CARTO + deck.gl applications Latest version **0.5.34** (published 2026-09-16) · MIT license · 0 weekly downloads ## Install ```sh npm install @carto/api-client pnpm add @carto/api-client yarn add @carto/api-client bun add @carto/api-client ``` ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types; pre 1.0. ## Facts | | | |---|---| | Version | 0.5.34 | | Published | 2026-09-16 | | First published | 2024-06-25 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM + CommonJS | | Dependencies | 7 | | Unpacked size | 7.3 MB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 3 | | Author | Don McCurdy | | Maintainers | jmtorrescartodb, juanra-carto, cartodb, shylpx, jaragon, aaranadev, zbigg, josmorsot, vmilan, felixpalmer, moicalcob, aalmonacid, jmgaya, menusal | ## Links - npm: https://www.npmjs.com/package/@carto/api-client - Repository: https://github.com/CartoDB/carto-api-client - Homepage: https://github.com/CartoDB/carto-api-client#readme - npm.io page: https://npm.io/package/@carto/api-client ## Dependencies (7) - [jsep](https://npm.io/package/jsep.md) ^1.4.0 - [h3-js](https://npm.io/package/h3-js.md) ^4.1.0 - [quadbin](https://npm.io/package/quadbin.md) ^0.4.1-alpha.0 - [d3-scale](https://npm.io/package/d3-scale.md) ^4.0.2 - [d3-format](https://npm.io/package/d3-format.md) ^3.1.2 - [@types/geojson](https://npm.io/package/@types/geojson.md) ^7946.0.16 - [@loaders.gl/schema](https://npm.io/package/@loaders.gl/schema.md) ^4.3.3 ## Recent versions - 0.5.34 (latest) — 2026-09-16 - 0.5.33-alpha.8f57a80.144 (alpha) — 2026-08-12 - 0.5.33 — 2026-08-21 - 0.5.33-alpha.c92492c.143 — 2026-08-11 - 0.5.33-alpha.7fc48f7.142 — 2026-08-10 - 0.5.33-alpha.6baf0ea.141 — 2026-08-10 - 0.5.33-alpha.dbc9b74.140 — 2026-08-03 - 0.5.33-alpha.7692e17.139 — 2026-08-03 - 0.5.33-alpha.3cccb70.138 — 2026-08-03 - 0.5.33-alpha.645887c.137 — 2026-08-03 - 0.5.32-alpha.fb236de.136 — 2026-07-31 - 0.5.32 — 2026-07-30 - 0.5.32-alpha.6cbd219.134 — 2026-07-30 - 0.5.32-alpha.02a4470.133 — 2026-07-24 - 0.5.32-alpha.723d642.132 — 2026-07-24 - … 159 more at https://npm.io/package/@carto/api-client/versions ## README # `@carto/api-client` JavaScript (and TypeScript) client library for [CARTO](https://carto.com/) APIs and framework-agnostic [CARTO + deck.gl](https://docs.carto.com/carto-for-developers/carto-for-deck.gl) applications. Includes: - [Widget](https://docs.carto.com/carto-for-developers/carto-for-react/guides/widgets) APIs - … TBD ## Installation Install `@carto/api-client`: ```bash npm install --save @carto/api-client ``` ## Documentation ### Fetching data Import `vectorTableSource`, `vectorQuerySource`, and other data source functions from the `@carto/api-client` package. These are drop-in replacements for the equivalent functions from the `@deck.gl/carto` package, and the same data source may be used with any number of layers or widgets. Tileset sources are not yet supported. ```javascript import { vectorTableSource } from '@carto/api-client'; const data = await vectorTableSource({ accessToken: '••••', connectionName: 'carto_dw', tableName: 'carto-demo-data.demo_tables.retail_stores' }); // → {name: string; value: number}[] const categories = await data.widgetSource.getCategories({ column: 'store_type', operation: 'count', }); // → {value: number} const formula = await data.widgetSource.getFormula({operation: 'count'}); // → {totalCount: number; rows: Record[]} const table = await data.widgetSource.getTable({ columns: ['a', 'b', 'c'], sortBy: ['a'], rowsPerPage: 20 }); ... ``` ### Column filter To filter the widget source by a non-geospatial column, pass a `filters` property to the source factory function. ```javascript import {vectorTableSource} from '@carto/api-client'; const data = await vectorTableSource({ accessToken: '••••', connectionName: 'carto_dw', tableName: 'carto-demo-data.demo_tables.retail_stores', filters: { store_type: {owner: 'widget-id', values: ['retail']}, }, }); ``` By default, filters affect all layers and widgets using a given data source. To exclude a particular widget from the filter, pass a `filterOwner` parameter matching the filters from which it should be excluded. In some cases, a widget's results should not be affected by a filter that the widget itself created. ```javascript // → {name: string; value: number}[] const categories = await data.widgetSource.getCategories({ filterOwner: 'widget-id', column: 'store_type', operation: 'count', }); ``` ### Spatial filter To filter the widget source to a spatial region, pass a `spatialFilter` parameter (GeoJSON Polygon or MultiPolygon geometry) to any data fetching function. ```javascript // → {name: string; value: number}[] const categories = await data.widgetSource.getCategories({ column: 'store_type', operation: 'count', spatialFilter: { type: "Polygon" coordinates: [ [ [-74.0562, 40.8331], [-74.0562, 40.6933], [-73.8734, 40.6933], [-73.8734, 40.8331], [-74.0562, 40.8331] ] ], } }); ``` To create a spatial filter from the current [deck.gl `viewState`](https://deck.gl/docs/developer-guide/views#using-a-view-with-view-state): ```javascript import {WebMercatorViewport} from '@deck.gl/core'; import {createViewportSpatialFilter} from '@carto/api-client'; const viewport = new WebMercatorViewport(viewState); const spatialFilter = createViewportSpatialFilter(viewport.getBounds()); ``` ### Specifying columns to fetch Factory functions, like `vectorTableSource`, support both layers and widgets. While reusing the same sources has advantages, including simplicity, it's important to understand which columns are fetched, which depends on the source type. - **Table sources:** Layers fetch only columns specified by the `columns` parameter. Widgets fetch only the columns they need, and are unaffected by the `columns` parameter. - **Query sources:** Source SQL query must include all columns needed by any layers or widgets using the source. Layers fetch only the subset specified by the `columns` parameter. Widgets fetch only the subset they need, and are unaffected by the `columns` parameter. - **Tileset sources:** Not yet supported. ## Versioning Package versioning follows [Semantic Versioning 2.0.0](https://semver.org/). ## License Provided as open source under [MIT License](./LICENSE.md). --- _Source: https://npm.io/package/@carto/api-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._