kibana/docs/maps/maps-getting-started.asciidoc

[role="xpack"]
[[maps-getting-started]]
== Getting started with Elastic Maps

You work with *Elastic Maps* by adding layers. The data for a layer can come from
sources such as {es} documents, vector sources, tile map services, web map
services, and more. You can symbolize the data in different ways.
For example, you might show which airports have the longest flight
delays by using circles from small to big. Or,
you might show the amount of web log traffic by shading countries from
light to dark.

[role="screenshot"]
image::maps/images/sample_data_web_logs.png[]

[[maps-read-only-access]]
NOTE: If you have insufficient privileges to create or save maps, a read-only icon
appears in the application header. The buttons to create new maps or edit
existing maps won't be visible. For more information on granting access to
Kibana see <<xpack-security-authorization>>.

[role="screenshot"]
image::maps/images/read-only-badge.png[Example of Maps' read only access indicator in Kibana's header]

[float]
=== Prerequisites
Before you start this tutorial, <<add-sample-data, add the web logs sample data set>>. Each
sample data set includes a map to go along with the data. Once you've added the data, open *Elastic Maps* and
explore the different layers of the *[Logs] Total Requests and Bytes* map.
You'll re-create this map in this tutorial.

[float]
=== Take-away skills
In this tutorial, you'll learn to:

* Create a multi-layer map
* Connect a layer to a data source
* Use symbols, colors, and labels to style a layer
* Create layers for {es} data

[role="xpack"]
[[maps-create]]
=== Creating a new map

The first thing to do is to create a new map.

. If you haven't already, open *Elastic Maps*.
. On the maps list page, click *Create map*.
. Set the time range to *Last 7 days*.
+
A new map is created using a base tile layer.
+
[role="screenshot"]
image::maps/images/gs_create_new_map.png[]

[role="xpack"]
[[maps-add-choropleth-layer]]
=== Adding a choropleth layer

Now that you have a map, you'll want to add layers to it.
The first layer you'll add is a choropleth layer to shade world countries
by web log traffic. Darker shades symbolize countries with more web log traffic,
and lighter shades symbolize countries with less traffic.

==== Add a vector layer from the Elastic Maps Service source

. In the map legend, click *Add layer*.
. Click the *EMS Boundaries* data source.
. From the *Layer* dropdown menu, select *World Countries*.
. Click the *Add layer* button.
. Set *Name* to `Total Requests by Country`.
. Set *Opacity* to 50%.
. Click *Add* under *Tooltip fields*.
. In the popover, select *ISO 3166-1 alpha-2 code* and *name* and click *Add*.

===== Join the vector layer with the sample web log index

You now have a vector layer containing the world countries.
To symbolize countries by web traffic, you'll need to augment the world country features with the count of Elasticsearch weblog documents originating from each country.
To do this, you'll create a <<terms-join, term join>> to link the vector source *World Countries* to
the {es} index `kibana_sample_data_logs` on the shared key iso2 = geo.src.

. Click plus image:maps/images/gs_plus_icon.png[] next to the *Term Joins* label.
. Click *Join --select--*
. Set *Left field* to *ISO 3166-1 alpha-2 code*.
. Set *Right source* to *kibana_sample_data_logs*.
. Set *Right field* to *geo.src*.
. Click *and use metric count*.
. Set *Custom label* to *web logs count*.

===== Set the layer style

All of the world countries are still a single color because the layer is using <<maps-vector-style-static, static styling>>.
To shade the world countries based on which country is sending the most requests, you'll need to use <<maps-vector-style-data-driven, data driven styling>>.

. Under *Fill color*, change the selected value from *Solid* to *By value*.
. In the field select input, select *web logs count*.
. Select the grey color ramp.
. Under *Border color*, change the selected color to *white*.
. Click *Save & close*.
+
Your map now looks like this:
+
[role="screenshot"]
image::maps/images/gs_add_cloropeth_layer.png[]

[role="xpack"]
[[maps-add-elasticsearch-layer]]
=== Adding layers for {es} data

To avoid overwhelming the user with too much data at once, you'll add two layers for {es} data.

* The first layer will display individual documents.
The layer will appear when the user zooms in the map to show smaller regions.
* The second layer will show aggregated data that represents many documents.
The layer will appear when the user zooms out the map to show larger amounts of the globe.

==== Add a vector layer from the document source

This layer displays web log documents as points.
The layer is only visible when users zoom in the map past zoom level 9.

. In the map legend, click *Add layer*.
. Click the *Documents* data source.
. Set *Index pattern* to *kibana_sample_data_logs*.
. Click the *Add layer* button.
. Set *Name* to `Actual Requests`.
. Set *Visibilty* to the range [9, 24].
. Set *Opacity* to 100%.
. Click *Add* under *Tooltip fields*.
. In the popover, select *clientip*, *timestamp*, *host*, *request*, *response*, *machine.os*, *agent*, and *bytes* and click *Add*.
. Set *Fill color* to *#2200ff*.
. Click *Save & close*.
+
Your map now looks like this between zoom levels 9 and 24:
+
[role="screenshot"]
image::maps/images/gs_add_es_document_layer.png[]

==== Add a vector layer from the grid aggregation source

Aggregations group {es} documents into grids. You can calculate metrics
for each gridded cell.

You'll create a layer for aggregated data and make it visible only when the map
is zoomed out past zoom level 9. Darker colors will symbolize grids
with more web log traffic, and lighter colors will symbolize grids with less
traffic. Larger circles will symbolize grids with
more total bytes transferred, and smaller circles will symbolize
grids with less bytes transferred.

[role="screenshot"]
image::maps/images/grid_metrics_both.png[]

===== Add the layer

. In the map legend, click *Add layer*.
. Click the *Grid aggregation* data source.
. Set *Index pattern* to *kibana_sample_data_logs*.
. Set *Show as* to *clusters*.
. Click the *Add layer* button.
. Set *Name* to `Total Requests and Bytes`.
. Set *Visibility* to the range [0, 9].
. Set *Opacity* to 100%.

===== Configure the aggregation metrics

. Click *Add metric* under of *Metrics* label.
. Select *Sum* in the aggregation select.
. Select *bytes* in the field select.

===== Set the layer style

. In *Layer style*, change *Symbol size*:
  .. Set *Min size* to 7.
  .. Set *Max size* to 25.
  .. Change the field select from *count* to *sum of bytes*.
. Click *Save & close* button.
+
Your map now looks like this between zoom levels 0 and 9:
+
[role="screenshot"]
image::maps/images/sample_data_web_logs.png[]

[role="xpack"]
[[maps-save]]
=== Saving the map
Now that your map is complete, you'll want to save it so others can use it.

. In the application toolbar, click *Save*.
. Enter `Tutorial web logs map` for the title.
. Click *Save*.
+
You have completed the steps for re-creating the sample data map.

*Next steps:*

* Continue with this tutorial and <<maps-embedding, use your map in a Kibana dashboard>>.
* Create a map using your own data. You might find these resources helpful:
** <<heatmap-layer, Heat map layer>>
** <<tile-layer, Tile layer>>
** <<vector-layer, Vector layer>>

[role="xpack"]
[[maps-embedding]]
=== Adding the map to a dashboard
You can add your saved map to a {kibana-ref}/dashboard.html[dashboard] and view your geospatial data alongside bar charts, pie charts, and other visualizations.

. In the side navigation, click *Dashboard*.
. Click *Create new dashboard*.
. Set the time range to *Last 7 days*.
. Click *Add*.
+
A panel opens with a list of objects that you can add to the dashboard.  You'll add a map and two visualizations.
+
. Set the *Types* select to *Map*.
. Click the name of your saved map or the *[Logs] Total Requests and Bytes* map included with the sample data set to add a map to the dashboard.
. Set the *Types* select to *Visualization*.
. Click *[Logs] Heatmap* to add a heatmap to the dashboard.
. Click *[Logs] Visitors by OS* to add a pie chart to the dashboard.
. Close the panel.
+
Your dashboard should look like this:
+
[role="screenshot"]
image::maps/images/gs_dashboard_with_map.png[]

==== Exploring your data using filters

You can apply filters to your dashboard to hone in on the data that you are most interested in.
The dashboard is interactive--you can quickly create filters by clicking on the desired data in the map and visualizations.
The panels are linked, so that when you apply a filter in one panel, the filter is applied to all panels on the dashboard.

. In the *[Logs] Visitors by OS* visualization, click on the *osx* pie slice.
+
Both the visualizations and map are filtered to only show documents where *machine.os.keyword* is *osx*.
The *machine.os.keyword: osx* filter appears in the dashboard query bar.
+
. Click the *x* to remove the *machine.os.keyword: osx* filter.
. In the map, click in the United States vector.
. Click plus image:maps/images/gs_plus_icon.png[] next to the *iso2* row in the tooltip.
+
Both the visualizations and the map are filtered to only show documents where *geo.src* is *US*.
The *geo.src: US* filter appears in the dashboard query bar.
+
Your dashboard should look like this:
+
[role="screenshot"]
image::maps/images/gs_dashboard_with_terms_filter.png[]