# Integrating Builder maps in your application

## Introduction <a href="#introduction" id="introduction"></a>

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](/carto-user-manual/maps.md) 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

{% hint style="success" %}
**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.
{% endhint %}

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.

{% code overflow="wrap" %}

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

{% endcode %}

Our documentation covers [how to embed maps in HTML](/carto-user-manual/maps/sharing-and-collaboration/embedding-maps.md), including a reference for advanced controls via URL parameters. An [example for embedding with URL parameters](https://academy.carto.com/building-interactive-maps/sharing-and-collaborating/dynamically-control-your-maps-using-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](/carto-user-manual/maps/sharing-and-collaboration/embedding-maps.md#private-embedding).

<figure><img src="/files/PQdRlgVfPmpkLgFlQkMJ" alt=""><figcaption><p>Example of an embedded map in an application. The application can control the map via URL parameters.</p></figcaption></figure>

## Method 2: fetchMap

{% hint style="success" %}
**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.
{% endhint %}

Teams looking to integrate information from their CARTO Builder maps into their custom applications can use [**`fetchMap`**](/carto-for-developers/reference/fetchmap.md)**, 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.

{% code overflow="wrap" %}

```typescript
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});
```

{% endcode %}

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.

<figure><img src="/files/uiIFkGslDkXJrv3lcalM" alt=""><figcaption></figcaption></figure>

### Using fetchMap with private maps

Using **private (non-public) maps** with fetchMap is possible: developers just need to provide a valid [OAuth Access Token](/carto-for-developers/key-concepts/authentication-methods/oauth-access-tokens.md) 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](/carto-for-developers/reference/fetchmap.md), or check [our working example](/carto-for-developers/examples.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/carto-for-developers/key-concepts/rapid-map-prototyping.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.