Use Boundaries in your application

The features and capabilities described in this guide are still experimental and they might be subject to change in the future.

Introduction

In this guide, we will cover the basics of a new method for visualizing aggregated data within predefined or customized boundaries, such as postal codes or census areas. We are calling this method "Boundaries"

This method offers potential performance enhancements, scaling visualization capabilities to higher levels. By separating the data from the static geometries that encapsulate it, this feature facilitates dynamic filtering and aggregation while simplifying architectural complexity.

Because both the data and geometries share a matching column with an ID (eg: zip code), we are now able to perform the aggregation without using the geometry, only to incorporate the geometries later to visualize the result.

This approach provides an alternative to traditional methods of preparing, storing, and serving geometries for each request, offering a streamlined and efficient solution.

Find a boundary

We have created a catalog that includes known boundaries for some countries. It currently covers different type of boundaries for the United States, Canada, Mexico, United Kingdom and Spain.

Explore the catalog from the CARTO Boundaries Explorer application.

Select a country and the corresponding tileset to the boundary you're looking for. Then select the data warehouse between BigQuery and Snowflake, and click on "Use this boundary in your app" button.

Using a Boundary

This dialog shows all the necessary information to use a boundary in an application. Depending on the data warehouse selected in the explorer, you will find a different type of Boundary ID.

BigQuery

For BigQuery, you also need to select a region that matches the region where your data is hosted. The boundaries' tilesets are available in different public BigQuery datasets maintained by CARTO.

Copy the Boundary ID and use it directly in your application's code following the provided example.

Snowflake

For Snowflake, CARTO publishes the collection of boundaries in this public listing.

Once you have the CARTO Boundaries database available in your Snowflake account, use the Boundary ID, making sure you use the appropriate database name.

Create a custom boundary

While the collection of boundaries provided by CARTO will be expanding and covering more territories over time, you might need to use a custom set of geographies in your application. For example, when working with agricultural parcel data or disputed territory boundaries.

Generating a tileset that can be used as a boundary is easy using the CARTO Analytics Toolbox procedures in the tiler module. See the reference for BigQuery and Snowflake.

The key for a tileset to be usable as a boundary is that it includes an additional geoid column. For this, make sure that you add the "calculate_geoids": true option to the tileset creation procedure.

These are examples for creating boundary tileset in BigQuery and Snowflake:

BigQuery

CALL `carto-un`.carto.CREATE_SIMPLE_TILESET(
    '(SELECT geom, geoid, NAME_0 as name FROM `project.dataset.geography_admin_0_countries`)',
    '`carto-boundaries.us.tileset_glo_adm0_v1`',
    '''
    {
      "max_tile_size_kb": 1536, 
      "max_tile_size_strategy": "drop_fraction_as_needed", 
      "tile_feature_order": "ST_AREA(geom) DESC", 
      "geom_column": "geom", 
      "calculate_geoids": true, 
      "zoom_min": 0, 
      "zoom_max": 4, 
      "properties": {
        "geoid": "String", 
        "name": "String"
        }
    }
    '''
);

Snowflake

CALL CARTO.CARTO.CREATE_SIMPLE_TILESET( 
  '(SELECT GEOM, GEOID, NAME FROM DATABASE.PUBLIC.GEOGRAPHY_ADMIN_0_COUNTRIES)', 
  'CARTO_BOUNDARIES.TILESETS.TILESET_GLO_ADM0_V1', 
  '{
    "max_tile_vertices": 200000, 
    "max_tile_size_strategy": "drop_fraction_as_needed", 
    "geom_column": "GEOM", 
    "calculate_geoids": true, 
    "single_query": true, 
    "zoom_min": 1, 
    "zoom_max": 4, 
    "properties": {
      "GEOID": "String", 
      "NAME": "String"
      }
    }' 
  );

Create an API Access Token

As with any other interaction with the CARTO APIs, for using Boundaries a user needs to provide an API Access Token with the appropriate grants.

Make sure that your API Access Token has grants for both the boundary's tilesetTableName and the propertiesSqlQuery

Check this documentation to learn more about creating API Access Tokens.

Type or paste the Boundary ID, as well as the source for the data to be joined with.

Build your app

Take a look at the live example for an application using Boundaries here.

See below the most relevant part of the example:

import {Deck} from '@deck.gl/core/typed';
import {vectorQuerySource, vectorTileLayer, …} from'@deck.gl/carto/typed';


// Optionally reuse authentication and connection parameters across sources

const apiBaseUrl = …
const accessToken = …
const connectionName = 'carto_dw';
const cartoConfig = {apiBaseUrl, accessToken, connectionName};

// Set up one or more CARTO boundary sources

const avgTicketByZipcode = boundaryQuerySource({
   ...cartoConfig,
   tilesetTableName: 'carto-boundaries.us.tileset_usa_zipcode_v1', // boundaries
   propertiesSqlQuery: `SELECT geoid, AVG(avg_ticket) as avg_ticket 
       FROM project.dataset.big_data_table
       GROUP BY geoid`, // data
   matchingColumn: 'geoid',
 )};

// Whatever your app does, but you’ll need to somehow initialize deck.gl

deck = new Deck({
   …
   layers: [],
});


// Use your boundary sources as usual in your tile layers from the CARTO module

 const layers = [
   new VectorTileLayer({
     data: avgTicketByZipcode,
     getFillColor: … // style by avg_ticket!
   })
 ];