Main Content


Add custom basemap


addCustomBasemap(basemapName,URL) adds the custom basemap specified by URL to the list of basemaps available for use with mapping functions. basemapName is the name you choose to call the custom basemap. Added basemaps remain available for use in future MATLAB® sessions.


addCustomBasemap(___,Name,Value) specifies name-value arguments that set additional parameters of the basemap.


collapse all

Add a custom basemap to view locations on an OpenTopoMap® basemap, then remove the custom basemap from siteviewer.

Initialize simulation variables to:

  • Define the name that you will use to specify your custom basemap.

  • Specify the website that provides the map data. The first character of the URL indicates which server to use to get the data. For load balancing, the provider has three servers that you can use: a, b, or c.

  • Create an attribution to display on the map that gives credit to the provider of the map data. Web map providers might define specific requirements for the attribution.

  • Define a display name for the custom map.

name = 'opentopomap';
url = '';
copyright = char(uint8(169));
attribution = copyright + "OpenStreetMap contributors";
displayName = 'Open Topo Map';

Use addCustomBasemap to load the custom basemap, and then create a siteviewer object that loads the custom basemap.

viewer = siteviewer('Basemap',name);

After a custom basemap is added to siteviewer, the custom map is available for future calls to siteviewer. Note the 'Open Topo Map' icon in the Imagery tab.


Use removeCustomBasemap to remove the custom basemap from future calls to siteviewer. Note the 'Open Topo Map' icon is no longer available in the Imagery tab.


Input Arguments

collapse all

Name used to identify basemap programmatically, specified as a string scalar or character vector.

Example: 'openstreetmap'

Data Types: string | char

Parameterized map URL, specified as a string scalar or character vector. A parameterized URL is an index of the map tiles, formatted as ${z}/${x}/${y}.png or {z}/{x}/{y}.png, where:

  • ${z} or {z} is the tile zoom level.

  • ${x} or {x} is the tile column index.

  • ${y} or {y} is the tile row index.

Example: 'https://hostname/${z}/${x}/${y}.png'

Data Types: string | char

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: addCustomBasemap(basemapName,URL,"Attribution",attribution)

Attribution of the custom basemap, specified as a string scalar, string array, character vector, or cell array of character vectors. To create a multiline attribution, specify a string array or nonscalar cell array of character vectors.

When you create a custom basemap from a URL, the default attribution is 'Tiles courtesy of DOMAIN_NAME_OF_URL', where DOMAIN_NAME_OF_URL is the domain name from the URL input argument. If the host is 'localhost', or if URL contains only IP numbers, specify the attribution as an empty string ("").

Example: "Credit: U.S. Geological Survey"

Data Types: string | char | cell

Display name of the custom basemap, specified as a string scalar or character vector.

Example: "OpenStreetMap"

Data Types: string | char

Maximum zoom level of the basemap, specified as an integer in the range [0, 25].

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Map is deployable using MATLAB Compiler, specified as a numeric or logical 0 (false) or 1 (true).

Data Types: logical


The addCustomBasemap function does not support adding custom basemaps from vector map tiles.


  • You can find tiled web maps from various vendors, such as OpenStreetMap®, the USGS National Map, Mapbox, DigitalGlobe, Esri® ArcGIS Online, the Geospatial Information Authority of Japan (GSI), and HERE Technologies. Abide by the map vendors terms-of-service agreement and include accurate attribution with the maps you use.

  • If you have Mapping Toolbox™, you can create custom basemaps from MBTiles files. For more information, see addCustomBasemap (Mapping Toolbox).

  • To access a list of available basemaps, press Tab before specifying the basemap in your plotting function. This image shows a sample list of available basemaps, including several custom basemaps from the USGS National Map.

    Plotting function in MATLAB with list of available basemaps to select from