URL parameters

URL parameters provide a versatile way to dynamically customize the presentation of your Builder map in viewer mode, enabling you to create tailored views for specific audiences without the need to create and manage multiple duplicated maps.

Using URL Parameters

Automatic interaction

When interacting with the viewer mode of a Builder map, any changes made are automatically reflected in the URL. For instance, if you use the Search location bar to find a specific address, the location will automatically be appended to the URL parameter, as shown in this example:

https://clausa.app.carto.com/map/5d942679-411f-4ab7-afb7-0f6061c9af63?search=New+York

Manual addition

You can manually add URL parameters to customize the behavior of your map in viewer mode. To manually include URL parameters, follow these guidelines, along with the parameter table referencer:

• Use the '&' symbol to separate multiple parameters.

• The first parameter should start with a '?' symbol.

• Replace spaces in the URL with plus signs '+'.

• Utilize encoded formatting, such as %28 and %29 for parentheses or %2C for commas, when needed.

Limit Considerations

• URL Length: The URL of the map has a limit of 2083 characters. Exceeding this limit may result in the removal of parameters from the URL. Keep your URL within this limit for desired map settings.

• Time Series Widget: URL parameters do not support the Time Series Widget settings.

• Parameter Validation: Ensure correct parameter formatting and validity. Invalid or meaningless parameters will be ignored by the map.

• Edit Mode: Parameters are only accepted when viewing the map either automatically or by manual input. Please note that any additions of parameters in the map URL editor mode will be ignored.

Parameter Reference

Refer to the table below for detailed information about each parameter that can be included in the URL to customize your map.

Parameter	Description
lat / lng	Sets the center of the map. Syntax rules: lat specifies the latitude lng specifies the longitude of the map's center. Values should be in decimal degrees Example: lat=27.731667&lng=-81.346962
zoom	Defines the zoom level of the map, controlling the scale of the view. Higher values zoom in closer to the surface. Example: zoom=10
mask	Defines a geographic area to filter map layers and widgets using a polygon. Syntax rules: Must be in WKT POLYGON format. Use %28 and %29 for parentheses. Use %2C for commas. + for spaces between coordinates. Example: mask=POLYGON+%28%28-2.601981+51.452270%2C+-2.601877+51.450410%2C+-2.594073+51.450319%2C+-2.594632+51.452358%2C+-2.601981+51.452270%29%29
search	Allows searching for a coordinate or address. When used, it centers the map on the specified location, updates the Search location bar, and places a marker icon at the location. Syntax rules: Coordinates must be in decimal degrees format. Use + to replace spaces within an address or between coordinate values. Use %2C to separate latitude and longitude values in coordinates. Examples: Address: search=broadway+new+york Coordinates: search=40.790886%2C+-73.974709
widget_[widget_id]	Applies filters to widgets in the map. The unique widget_id can be obtained using the "Copy ID" functionality available on each widget on Editor mode. Syntax rule: Replace [widget_id] with the widget's actual ID. Use + to indicate spaces within concatenated filter values. Use %2C to separate different filter ranges for Histogram widget. Time Series widgets is not supported by URL parameters. Example: Pie Widget: widget_5c7eb73e-5e2f-4639-90af-1b82b80a1969=Department+Store Histogram: widget_6a1a3172-1bc2-49be-89a8-c1b008f4e43e=1413506.6-1526970.5
param_[sql_name]	Update the input values in SQL Parameter Controls updating the parameters applied in your SQL query sources. Syntax rules: Substitute [sql_name] with the actual name SQL name of the parameter without brackets. Encode spaces within text values with +. Format date values as YYYY-MM-DD. Encode dashes - in numeric ranges with %2D for specifying value intervals. Example: Date Parameter: param_event_date_from=2017-01-03&param_event_date_to=2017-01-11 Numeric Parameter param_accident_influence_radius=70 Text Parameter: param_route_type=Popular+Busier+Roads
layers	Specify which layers are visible in the map. Syntax rule: List the indices of the visible layers separated by commas without spaces. Each index corresponds to a layer's position in the Builder, starting from 0. Example: layers=0,1
pitch	Adjusts the vertical angle of the map view in degrees, enhancing the perspective or 3D visualization effect. Syntax rule: The value can range from 0 (orthogonal view, directly above) to 60 degrees (tilted view, providing depth and perspective). Example: pitch=35
bearing	Adjusts the horizontal angle or bearing of the map view, specifying the orientation with respect to the cardinal directions. Syntax rule: The value is provided in degrees, measured clockwise, with North as 0 degrees, East as 90 degrees, South as 180 degrees, and West as 270 degrees. Example: bearing=180