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

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

++++
<titleabbrev>Get started</titleabbrev>
++++



You work with 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 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]]
=== Create a map

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

. If you haven't already, open the menu, then click *{kib} > 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]]
=== Add 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.

. Click *Add layer*.
. Select *Choropleth*.
. From the *Layer* dropdown menu, select *World Countries*.
. Under *Statistics source*, set *Index pattern* to *kibana_sample_data_logs*.
. Set *Join field* to *geo.src*.
. 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*.
. Under *Fill color*, 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]]
=== Add layers for the {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 display 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 to display individual documents

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

. Click *Add layer*.
. Select *Documents*.
. 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 to display aggregated data

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

. Click *Add layer*.
. Select *Clusters and grids*.
. Set *Index pattern* to *kibana_sample_data_logs*.
. 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]]
=== Save 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]]
=== Add 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.

. Open the menu, then go to *Dashboard*.
. Click *Create 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[]

==== Explore 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[]