Embedding maps

Maps built with CARTO can be easily embedded in other websites or applications, using an <iframe> HTML element. This is a great way for your maps to make a larger impact by reaching a larger audience, both outside and inside your organization.

Additionally, embedding a map can be a way to create beautiful data stories by wrapping your map with richer, interactive context and storytelling in a presentation or a website.

For an in-depth tutorial on creating and embedding maps, we highly recommend visiting the CARTO Academy guide, which contains practical step-by-step resources.

Example of an embedded map with interactive controls via URL parameters

Embedding a map

To embed a map, simply click on "Share" as seen in Publishing and sharing maps, and copy the embed code available in the sharing dialog. The resulting code should be similar to this one.

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

Public embedding

Maps that are shared as Public can be embedded anywhere without restrictions. Public maps protected with a password can also be embedded, with the additional password requirement.

Private embedding

You can control who can view your embedded map by sharing it exclusively with your Organization or with specific Groups. When you embed a non-public map, users need to meet the following requirements to view the map:

• Users must be previously logged-in to CARTO in the same browser as the embedded map

• Users must have access to the map (for example, they need to be part of the group that map is shared with)

• CARTO needs to be able to access cookies in the user browser. Learn more in the known limitations section of this page.

If the user has access but is not currently logged-in to CARTO, they will need to login in a separate tab/window and refresh the page containing the embedded map.

The code for private embedding will soon be available directly in the sharing modal. In the meantime, just replace the src URL in your iframe code with your shared map URL, using the /viewer/ path instead of /map/ or /builder/. For example:

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

Interacting with embedded maps

Users can interact with the embedded map in the same way they would in a standalone window by engaging with the map layers, widgets, SQL parameters...

An additional way to interact with the embedded map is by modifying the URL parameters. This is particularly interesting because it allows the parent application to control the state of the embedded CARTO map.

By modifying dynamically URL parameters in your embedded map, you can, for example:

• Control the map zoom and camera from user controls in your parent application

• Modify the map filters (widgets and parameters) when the users selects different options in your parent application

• Show/hide layers based on the user preferences in your parent application

Known limitations

1. The parent application must specify a valid origin HTTP header for the CARTO embedded map to load. This is a security requirement.

2. Clicks inside the embedded map (such as filtering or zooming) can't be tracked by the parent application. If you're interested in this use case, please contact us.

3. For private embedding: If the user browser does not allow access to cookies to the CARTO embedded iframe, a screen will pop up, prompting for permission.

   • Some browsers such as Firefox or Brave offer advanced privacy/tracking protection that might interfere with the CARTO embedded iframe. While these features are great for user privacy, they also disable legitimate secure use cases like this one. Users can disable these protections.