Main Content

addCustomBasemap

Add custom basemap

collapse all in page

Syntax

addCustomBasemap(basemapName,URL)
addCustomBasemap(___,Name=Value)

Description

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.

example

Examples

collapse all

Open Live Script

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

Figure Geographic Player contains an axes object with type geoaxes. The geoaxes object is empty.

Display the full route.

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

Figure Geographic Player contains an axes object with type geoaxes. The geoaxes object contains 2 objects of type line, scatter.

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';

Figure Geographic Player contains an axes object with type geoaxes. The geoaxes object contains 2 objects of type line, scatter.

Display the route again.

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

Figure Geographic Player contains an axes object with type geoaxes. The geoaxes object contains 4 objects of type line, scatter.

Display the positions of the vehicle in a sequence.

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

Figure Geographic Player contains an axes object with type geoaxes. The geoaxes object contains 6 objects of type line, scatter, text.

Open Live Script

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: "opentopomap"

Data Types: string | char

Parameterized map URL, specified as a string scalar or character vector.

The parameterized map URL typically includes:

  • The URL of the basemap tiles.

  • An index of the map tiles, formatted as ${z}/${x}/${y} or ${z}/${y}/${z}, where z is the tile zoom level, x is the tile column index, and y is the tile row index.

  • The file format of the map tiles. The addCustomBasemap function can read tiles in image formats supported by the imread function and tiles in PBF format (requires Mapping Toolbox™) when the map tiles are hosted by Esri®. Depending on the data provider, map tiles are available in different file formats.

The way you structure this argument can depend on the data provider. For more information about how to structure a URL, see Examples or ask your data provider.

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

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.

Example: addCustomBasemap(basemapName,URL,Attribution="My attribution") specifies the attribution for the custom basemap.

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

Example: addCustomBasemap(basemapName,URL,"Attribution","My attribution") specifies the attribution for the custom basemap.

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 a 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: "OpenTopoMap"

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

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.

  • Mapping Toolbox enables additional strategies for adding custom basemaps. For example, you can add custom basemaps from vector basemaps hosted by Esri, from MBTiles files, or from georeferenced images. Several of these strategies do not require internet access. For more information, see addCustomBasemap (Mapping Toolbox) and Use Basemaps in Offline Environments (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

See Also

| | | | (Mapping Toolbox) | (Mapping Toolbox)

Topics