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.

You can use the custom basemap with the geoplayer object and with MATLAB geographic axes and charts.


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


collapse all

This example shows how to display a driving route and vehicle positions on an OpenStreetMap® basemap.

Add the OpenStreetMap basemap to the list of basemaps available for use with the geoplayer object. After you add the basemap, you do not need to add it again in future sessions.

name = 'openstreetmap';
url = '${z}/${x}/${y}.png';
copyright = char(uint8(169));
attribution = copyright + "OpenStreetMap contributors";

Load a sequence of latitude and longitude coordinates.

data = load('geoRoute.mat');

Create a geographic player. Center the geographic player on the first position of the driving route and set the zoom level to 12.

zoomLevel = 12;
player = geoplayer(data.latitude(1),data.longitude(1),zoomLevel);

Display the full route.


By default, the geographic player uses the World Street Map basemap ('streets') provided by Esri®. Update the geographic player to use the added OpenStreetMap basemap instead.

player.Basemap = 'openstreetmap';

Display the route again.


Display the positions of the vehicle in a sequence.

for i = 1:length(data.latitude)

Display a driving route on a basemap provided by HERE Technologies. To use this example, you must have a valid license from HERE Technologies.

Specify the basemap name and map URL.

name = 'herestreets';
url = ['', ...

Maps from HERE Technologies require a valid license. Create a dialog box. In the dialog box, enter the Access Key ID corresponding to your HERE license.

prompt = {'HERE Access Key ID:'};
title = 'HERE Tokens';
dims = [1 40]; % Text edit field height and width
hereTokens = inputdlg(prompt,title,dims);

If the license is valid, specify the HERE credentials and a custom attribution, load coordinate data, and display the coordinates on the HERE basemap using a geoplayer object. If the license is not valid, display an error message.

if ~isempty(hereTokens)
    % Add HERE basemap with custom attribution.
    url = sprintf(url,hereTokens{1});
    copyrightSymbol = char(169); % Alt code
    attribution = [copyrightSymbol,' ',datestr(now,'yyyy'),' HERE'];

    % Load sample lat,lon coordinates.
    data = load('geoSequence.mat');

    % Create geoplayer with HERE basemap.
    player = geoplayer(data.latitude(1),data.longitude(1), ...
    % Display the coordinates in a sequence.
    for i = 1:length(data.latitude)

    error('You must enter valid credentials to access maps from HERE Technologies');

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 comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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

Attribution of custom basemap, specified as the comma-separated pair consisting of 'Attribution' and a string scalar, string array, character vector, or cell array of character vectors. If the host is 'localhost', or if URL contains only IP numbers, specify an empty value (''). To create a multiline attribution, specify a string array or nonscalar cell array of character vectors.

If you do not specify an attribution, the default attribution is 'Tiles courtesy of DOMAIN_NAME_OF_URL', where the addCustomBasemap function obtains the domain name from the URL input argument.

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

Data Types: string | char | cell

Display name of the custom basemap, specified as the comma-separated pair consisting of 'DisplayName' and a string scalar or character vector.

Example: 'OpenStreetMap'

Data Types: string | char

Maximum zoom level of the basemap, specified as the comma-separated pair consisting of 'MaxZoomLevel' and 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 the comma-separated pair consisting of 'IsDeployable' and false or true.

If you are deploying a map application and want users to have access to the added basemap, set 'IsDeployable' to true. Maps in the geoplayer object are not deployable. If you are using a geoplayer object, leave 'IsDeployable' set to false.

Data Types: logical


  • 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.

  • To access a list of available basemaps, press Tab before specifying the basemap in your plotting function.

Introduced in R2019a