Integrating Builder maps in your application

Introduction

As we've seen in previous concepts, CARTO allows developers to build completely custom geospatial applications at scale, powered by their data warehouse. However, some teams with a mix of skill sets (ie: developers and non-developers) may desire to build even faster, using CARTO Builder to:

• Prototype quickly the cartography to see how maps will look in the application

• Make styling changes and other adjustments without having to edit code

• Create and organize a repository of geospatial layers that will be used in the application

To accelerate those teams and use cases, we've developed different systems to integrate maps created with CARTO Builder in your CARTO for Developers application. The recommended method will depend on your specific needs.

Method 1: embedding

We recommend embedding when: You just want to integrate in your application maps created with CARTO Builder with their exact look and feel, and all their features: widgets, interactions, SQL parameters, controls... Your app may communicate with the embedded map, but no customizations are required.

Embedding a CARTO Builder map in your custom application is quite straightforward. You just need to copy the embed code generated in your map and use it in your application's HTML.

<iframe 
    width="100%" 
    height="640px" 
    src="https://clausa.app.carto.com/map/ff76a0cd-fd9c-4893-8c2b-d9c587f2d699"></iframe>

Our documentation covers how to embed maps in HTML, including a reference for advanced controls via URL parameters. An example for embedding with URL parameters can be found in our CARTO Academy.

Private (non-public) maps can also be embedded, but they may require an additional login step that can't be inherited from the application context. Learn more about private embedding.

Example of an embedded map in an application. The application can control the map via URL parameters.

Method 2: fetchMap

We recommend fetchMap when: You want to retrieve details from a CARTO Builder map such as data sources, layers or styling, but you want to integrate them with your own application functionalities, seamless login experience, or look and feel.

Teams looking to integrate information from their CARTO Builder maps into their custom applications can use fetchMap, a function that returns the details for a specific map in a structured JSON that can be then used to feed sources, layers, and other elements in a CARTO + deck.gl application.

Developers can then choose how to use this information, with varying degrees of customization and automation.

import {Deck} from '@deck.gl/core';
import {fetchMap} from '@carto/api-client';

const cartoMapId = 'ff6ac53f-741a-49fb-b615-d040bc5a96b8';
const mapData = await fetchMap({cartoMapId, credentials, autoRefresh, onNewData});

By merging the response from fetchMap with the rest of the application, developers can achieve exactly the experience that the app should offer, while dynamically retrieving details that have been configured in CARTO first.

Using fetchMap with private maps

Using private (non-public) maps with fetchMap is possible: developers just need to provide a valid OAuth Access Token that represents a user with access to the map.

Suggested workflows using fetchMap

We've compiled a list of use cases that, from our experience, are accelerated by integrating fetchMap:

• A development team can prototype maps quicker in a WYSIWYG experience, without having to code deck.gl styles from scratch.

• A team of cartographers can modify the application layer styles without editing the code, while the developers can focus on the integration of those layers.

• A team of data engineers/analysts without strong frontend skill sets can own the data and the visualization, while the developers can focus on the application functionality.

• An application development team can use CARTO Builder as a repository and manager of the maps and layers used in an application, using tags and other resources to organize the content.

Getting started with fetchMap

To start building with fetchMap take a look at our technical reference, or check our working example.