Custom basemaps for region and coordinate maps in Kibana

By
Nick Peihl

Editor's Note (January 16, 2020): This post has been updated to reflect breaking changes to tilemap parameters in version 7 of Kibana. Previous versions of Kibana may use tilemap instead of map.tilemap.

Previously, we discussed using custom region maps in Kibana. Today let’s talk about using custom basemaps in your coordinate and regions in Kibana. By default, region maps and coordinate maps in Kibana use basemaps from our Elastic Maps Service based on data from Natural Earth and OpenStreetMap. However, that doesn’t mean you are required to use our services. Perhaps Elastic Maps Service is not available in your area. Or you run Elasticsearch and Kibana in an air-gapped environment. Or maybe you just don’t like our basemap style (). If so, you can configure Kibana to use a custom basemap for all your region maps and coordinate maps.

There are two ways to configure Kibana with custom basemaps. You can define a single custom tile-server in the kibana.yml. That custom layer you can then use in your region or coordinate maps visualizations. You could also directly configure a custom WMS server, right inside your visualization.

Setting a default basemap in Kibana

The default basemap in Kibana is hosted by our Elastic Maps Service. But you can change the default in the kibana.yml settings for Kibana. You can use a third-party tile hosting service or you can host your own tile service. The Elastic Maps Service basemap is still an option in your region maps or coordinate maps unless you set the map.includeElasticMapsService: false parameter in kibana.yml.

Third-Party Basemaps

There are many companies and organizations that provide APIs for web map services. These are just a few examples that we’ve found..

MapTiler

MapTiler provides APIs for pre-built and custom-styled raster tile map services based on OpenStreetMap data. To use MapTiler basemaps in Kibana, you will need to sign up for the Raster or Raster Pro plan. The Raster plan allows you to use MapTiler’s existing basemaps, while the Raster Pro plan allows you to style your own maps.

After signing in to your account, select one of the available maps. Scroll down the page to locate the “Raster tiles” URL. Add this URL to your kibana.yml file like this.

map.tilemap.url: https://maps.tilehosting.com/styles/topo/{z}/{x}/{y}.png?key=<YOUR_KEY_HERE>

The MapTiler Terms of Use specify that our maps must include attribution for OpenMapTiles and OpenStreetMap. We can do that by specifying the map.tilemap.options.attributions parameter in kibana.yml. Links in the attribution text should follow the Markdown link format. Attributions can also be separated by the pipe (|) character. Here is how we can do it for MapTiler in our kibana.yml.

map.tilemap.options.attribution: "&#xA9; [OpenMapTiles](http://www.openmaptiles.org/)|&#xA9; [OpenStreetMap contributors](http://www.openstreetmap.org/copyright)"

It may also be a good idea to change the map.tilemap.options.maxZoom parameter. By default this is 10 and we might need want to view larger scales in Kibana.

map.tilemap.options.maxZoom: 18

Congratulations! You now have a MapTiler basemap in Kibana.

MapTiler basemap in Kibana

But why are colors are all washed out in Kibana? It doesn’t match the basemap we have on the MapTiler website. By default, coordinate maps in Kibana desaturate the basemap colors so your datasets stand out. We can disable this by unchecking the “Desaturate tiles” checkbox in the Options tab.

Animation showing regular and desaturated tiles in Kibana

Mapbox

Mapbox also provides APIs for pre-built and custom-styled raster tile map services based on OpenStreetMap data. To use Mapbox basemaps in Kibana, you start by creating a map in Mapbox Studio by either publishing a pre-built basemap or create your own style.

We can easily get the published style as raster tiles by using the CARTO integration URL in the “Use style in GIS apps” section of your style webpage. Copy the paste the URL into your kibana.yml file as for the map.tilemap.url parameter.

map.tilemap.url: "https://api.mapbox.com/styles/v1/npeihl/cjfmr550y11o72snzikhdt1zo/tiles/256/{z}/{x}/{y}@2x?access_token=<YOUR_TOKEN_HERE>"

Check out Mapbox’s documentation for more information on how this works, including rate limits.

Animation showing the CARTO integration link on the Mapbox Studio webpage

You are required to attribute Mapbox and OpenStreetMap when you use Mapbox basemaps. Here is an example that follows Mapbox’s attribution guidelines.

map.tilemap.options.attribution: &#xA9; [Mapbox](https://www.mapbox.com/about/maps/)|&#xA9; [OpenStreetMap contributors](http://www.openstreetmap.org/copyright)|[Improve this map](https://www.mapbox.com/map-feedback/)

There is not currently a way to add the Mapbox wordmark image to Kibana region and coordinate maps as specified on the Mapbox attribution webpage. You should check with your Mapbox account representative to make sure you don’t violate their Terms of Service.

Here’s a screenshot showing a Mapbox basemap in Kibana.

Mapbox dark basemap in Kibana

ArcGIS Online/ ArcGIS Server

Raster tile basemaps are also available from Esri on ArcGIS Online Living Atlas. You may be required to sign up for an appropriate account in order to use these basemaps in Kibana. You may want to check with your Esri account representative to verify that your usage falls in their terms of use.

For this example we’ll check out the World Topographic basemap. Notice the Credits (Attribution) and URL sections on the right side of the page. Let’s set the attribution by copying and pasting the Credits section into our kibana.yml.

map.tilemap.options.attribution: "Sources: Esri, HERE, Garmin, Intermap, INCREMENT P, GEBCO, USGS, FAO, NPS, NRCAN, GeoBase, IGN, Kadaster NL, Ordnance Survey, Esri Japan, METI, Esri China (Hong Kong), swisstopo, &#xA9; OpenStreetMap contributors, GIS User Community"

Open the URL to the REST service and look for the small WMTS link near the top of the page. The ResourceUrl on the WMTS page tells us the URL template for this basemap is https://services.arcgisonline.com/arcgis/rest/services/World_Topo_Map/MapServer/WMTS/tile/1.0.0/World_Topo_Map/{Style}/{TileMatrixSet}/{TileMatrix}/{TileRow}/{TileCol}.jpg.

There is only one TileMatrixSet listed in the WMTS capabilities called GoogleMapsCompatible. There is also only one Style called default. TileMatrix refers to the zoom level parameter ({z}) in a tile map service request. TileRow and TileCol refer to {y} and {x}, respectively. Knowing this we can build the URL for our map.tilemap.url parameter.

map.tilemap.url: https://services.arcgisonline.com/arcgis/rest/services/World_Topo_Map/MapServer/WMTS/tile/1.0.0/World_Topo_Map/default/GoogleMapsCompatible/{z}/{y}/{x}.jpg

Look closely at the TileMatrix children in the WMTS definition. There are 23 zoom levels we can use. That might be overkill for your application, so let’s just set that to a reasonable 18.

map.tilemap.options.maxZoom: 18

Now we have the World Topographic basemap from Esri available for our Kibana region maps and coordinate maps.

Esri World Topographic basemap in Kibana

Wikimedia / OpenStreetMap

Like MapTiler and Mapbox, Wikimedia serves tile maps based on OpenStreetMap data. However, the Wikimedia basemap can not be customized. Wikimedia Map service can be used in third-party applications like Kibana for no cost, but you should review the Wikimedia Maps Terms of Service.

The URL template for the Wikimedia basemap that works with Kibana is https://maps.wikimedia.org/osm-intl/{z}/{x}/{y}.png. You must provide attribution to OpenStreetMap and I would also suggest linking to the Wikimedia Maps service Terms of Service page.

map.tilemap.url: https://maps.wikimedia.org/osm-intl/{z}/{x}/{y}.png
map.tilemap.options.attribution: [Wikimedia maps](https://wikimediafoundation.org/wiki/Maps_Terms_of_Use)|&#xA9; [OpenStreetMap](http://www.openstreetmap.org/copyright)
map.tilemap.options.maxZoom: 18

Wikimedia basemap in Kibana

Other Examples

Self-Hosted Basemaps

If Elastic Map Service isn’t available in your region or you run the Elastic stack on air-gapped servers you have the option to self-host your own basemaps. You also might want to disable requests to Elastic Maps Service by setting the map.includeElasticMapsService: false parameter in kibana.yml. Check out the Kibana Settings documentation for more information.

Here are a few examples for self hosting your own basemaps.

OpenMapTiles

OpenMapTiles is a solution designed to help you self-host worldwide basemaps based on OpenStreetMap data. OpenMapTiles can generate either raster map tiles or vector tiles. For compatibility with Kibana, you’ll need to make sure you generate raster map tiles.

Your parameters in kibana.yml will probably look something like this

map.tilemap.url: http://localhost:8080/styles/osm-bright/{z}/{x}/{y}.png
map.tilemap.options.attribution: "&#xA9; [OpenStreetMap](http://www.openstreetmap.org/copyright) contributors"

Geoserver / MapServer / ArcGIS Server

A more advanced scenario might have you running your own instance of Geoserver, MapServer, or ArcGIS Server. These software packages may or may not come with geospatial data needed to create basemaps. You might check out our blog post on using a custom Geoserver basemap with Elasticsearch.

To be compatible with Kibana, basemap tiles created with these software packages must be cached as raster tiles in the Web Mercator (EPSG: 3857) coordinate system. All of these software packages can publish WMTS services. You can review the ArcGIS Online example above to determine the map.tilemap.url parameter from WMTSCapabilities documents created by these software packages.

Customize a single region or coordinate map

The above examples apply globally to all region maps and coordinate maps in a single Kibana instance. But since Kibana v4.2 you can specify a separate Web Map Service (WMS) service as a basemap directly in each of your region maps or coordinate maps.

For example, maybe you want to add weather maps to your dashboard. The screenshot below shows two region maps focused on the United States. Each map is defined with a different WMS basemap from the US National Weather Service (NWS).

US National Weather Service basemaps in Kibana

The NWS GIS Web Services page contains links to REST APIs, many of which include WMS capabilities. For example, the Base Reflectivity Radar service metadata includes a link at the top of the page to the WMS GetCapabilities document. We can analyze this document to fill in the required information for the region map WMS parameters.

WMS server settings for Base Reflectivity Radar service: WMS Layers=1, WMS version=1.3.0, WMS format=image/png, WMS attribution=National Weather Service, WMS styles=default

The WMS url in the screenshot above appears truncated. The full url is https://idpgis.ncep.noaa.gov/arcgis/services/NWS_Observations/radar_base_reflectivity/MapServer/WMSServer as defined in the WMS GetCapabilities document.

The WMS service replaces the standard roads basemap for this region map. But we can still display the USA States vector layer for reference. In this example we don’t actually include any data from Elasticsearch.

National Weather Service Base Reflectivity Radar service and US States in Kibana

Get Creative

Whether you are creating your own basemaps or looking for new ways to customize maps for your Kibana dashboard, we hope you find these features of Kibana useful. Let us know on Discuss if you have questions about customizing Kibana region maps and coordinate maps.