Main Content

addCustomBasemap

Add custom basemap

Description

example

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.

example

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

Examples

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 = 'https://a.tile.openstreetmap.org/${z}/${x}/${y}.png';
copyright = char(uint8(169));
attribution = copyright + "OpenStreetMap contributors";
addCustomBasemap(name,url,'Attribution',attribution)

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.

plotRoute(player,data.latitude,data.longitude);

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.

plotRoute(player,data.latitude,data.longitude);

Display the positions of the vehicle in a sequence.

for i = 1:length(data.latitude)
   plotPosition(player,data.latitude(i),data.longitude(i))
end

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 = ['https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/', ...
    'newest/normal.day/${z}/${x}/${y}/256/png?apikey=%s'];

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'];
    addCustomBasemap(name,url,'Attribution',attribution);

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

    % Create geoplayer with HERE basemap.
    player = geoplayer(data.latitude(1),data.longitude(1), ...
        'Basemap','herestreets','HistoryDepth',Inf);
 
    % Display the coordinates in a sequence.
    for i = 1:length(data.latitude)
        plotPosition(player,data.latitude(i),data.longitude(i));
    end

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

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

To deploy a map application that uses a custom 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

Limitations

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

Tips

  • 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

Version History

Introduced in R2019a