diff --git a/docs/maps/geojson-upload.asciidoc b/docs/maps/geojson-upload.asciidoc new file mode 100644 index 0000000000000..d9b21f591f625 --- /dev/null +++ b/docs/maps/geojson-upload.asciidoc @@ -0,0 +1,43 @@ +[role="xpack"] +[[geojson-upload]] +== Upload GeoJSON data +*Elastic Maps* makes it easy to import geospatial data into the Elastic Stack. +Using the *GeoJSON Upload* feature, you can drag and drop your point and shape +data files directly into {es}, and then use them as layers +in the map. You can also use the GeoJSON data in the broader Kibana ecosystem, +for example, in visualizations and Canvas workpads. +[float] +=== Why GeoJSON? +GeoJSON is an open-standard file format for storing geospatial vector data. +Although many vector data formats are available in the GIS community, +GeoJSON is the most commonly used and flexible option. +[float] + +=== Upload a GeoJSON file +Follow the instructions below to upload a GeoJSON data file, or try the +<>. + +. Open *Elastic Maps*, and then click *Add layer*. +. Click *Upload GeoJSON vector file*. ++ +[role="screenshot"] +image::maps/images/fu_gs_select_source_file_upload.png[] + +. Use the file chooser to select a valid GeoJSON file. The file will load +a preview of the data on the map. +. Use the default *Index type* of {ref}/geo-point.html[geo_point] for point data, +or override it and select {ref}/geo-shape.html[geo_shape]. +All other shapes will default to a type of `geo_shape`. +. Leave the default *Index name* and *Index pattern* names (the name of the uploaded +file minus its extension). You might need to change the index name if it is invalid. +. Click *Import file*. ++ +Upon completing the indexing process and creating the associated index pattern, +the Elasticsearch responses are shown on the *Layer add panel* and the indexed data +appears on the map. The geospatial data on the map +should be identical to the locally-previewed data, but now it's indexed data from Elasticsearch. + +. To continue adding data to the map, click *Add layer* in the lower +right-hand corner. +. In *Layer settings*, adjust any settings or <> as needed. +. Click *Save & close*. diff --git a/docs/maps/images/fu_gs_final_map.png b/docs/maps/images/fu_gs_final_map.png new file mode 100644 index 0000000000000..1867e75bf64d0 Binary files /dev/null and b/docs/maps/images/fu_gs_final_map.png differ diff --git a/docs/maps/images/fu_gs_flight_paths.png b/docs/maps/images/fu_gs_flight_paths.png new file mode 100644 index 0000000000000..5376b4469c043 Binary files /dev/null and b/docs/maps/images/fu_gs_flight_paths.png differ diff --git a/docs/maps/images/fu_gs_lightning_intensity.png b/docs/maps/images/fu_gs_lightning_intensity.png new file mode 100644 index 0000000000000..d8ac8834a5d8f Binary files /dev/null and b/docs/maps/images/fu_gs_lightning_intensity.png differ diff --git a/docs/maps/images/fu_gs_new_england_map.png b/docs/maps/images/fu_gs_new_england_map.png new file mode 100644 index 0000000000000..2a5c9d38f362a Binary files /dev/null and b/docs/maps/images/fu_gs_new_england_map.png differ diff --git a/docs/maps/images/fu_gs_select_source_file_upload.png b/docs/maps/images/fu_gs_select_source_file_upload.png new file mode 100644 index 0000000000000..6939f6a82b297 Binary files /dev/null and b/docs/maps/images/fu_gs_select_source_file_upload.png differ diff --git a/docs/maps/index.asciidoc b/docs/maps/index.asciidoc index bb569a11ed874..56826c5209034 100644 --- a/docs/maps/index.asciidoc +++ b/docs/maps/index.asciidoc @@ -31,4 +31,6 @@ include::vector-layer.asciidoc[] include::maps-aggregations.asciidoc[] include::search.asciidoc[] include::connect-to-ems.asciidoc[] +include::geojson-upload.asciidoc[] +include::indexing-geojson-data-tutorial.asciidoc[] include::trouble-shooting.asciidoc[] diff --git a/docs/maps/indexing-geojson-data-tutorial.asciidoc b/docs/maps/indexing-geojson-data-tutorial.asciidoc new file mode 100644 index 0000000000000..5645567ec7e79 --- /dev/null +++ b/docs/maps/indexing-geojson-data-tutorial.asciidoc @@ -0,0 +1,142 @@ +[role="xpack"] +[[indexing-geojson-data-tutorial]] +== Indexing GeoJSON data tutorial + +In this tutorial, you'll build a customized map that shows the flight path between +two airports, and the lightning hot spots on that route. You'll learn to: + +* Import GeoJSON files into Kibana +* Index the files in {es} +* Display the data in a multi-layer map + +[float] +=== Before you begin + +This tutorial requires you to download the following GeoJSON sample data files. +These files are good examples of the types +of vector data that you can upload to Kibana and index in +Elasticsearch for display in *Elastic Maps*. + +* https://raw.githubusercontent.com/elastic/examples/master/Maps/Getting%20Started%20Examples/geojson_upload_and_styling/logan_international_airport.geojson[Logan International Airport] +* https://raw.githubusercontent.com/elastic/examples/master/Maps/Getting%20Started%20Examples/geojson_upload_and_styling/bangor_international_airport.geojson[Bangor International Airport] +* https://raw.githubusercontent.com/elastic/examples/master/Maps/Getting%20Started%20Examples/geojson_upload_and_styling/lightning_detected.geojson[Lightning detected] +* https://raw.githubusercontent.com/elastic/examples/master/Maps/Getting%20Started%20Examples/geojson_upload_and_styling/original_flight_path.geojson[Original flight path] +* https://raw.githubusercontent.com/elastic/examples/master/Maps/Getting%20Started%20Examples/geojson_upload_and_styling/modified_flight_path.geojson[Modified flight path] + +The data represents two real airports, two fictitious flight routes, and +fictitious lightning reports. You don't need to use all of +these files. Feel free to work with as many files as you'd like, or use valid GeoJSON +files of your own. + +[float] +[role="xpack"] +=== Create and set up a map + +. <>. +. Zoom in on the New England area in the northeast United States. ++ +You're adding flight paths to this area, and this +sets up the map for a good view of the data. ++ +[role="screenshot"] +image::maps/images/fu_gs_new_england_map.png[] + +[float] +[[upload-and-index-geojson-file]] +=== Upload and index GeoJSON files +For each GeoJSON file you downloaded, complete the following steps: + +. Below the map legend, click *Add layer*. +. From the list of layer types, click *Upload GeoJSON vector file*. +. Using the File Picker, upload the GeoJSON file. ++ +Depending on the geometry type of your features, this will +auto-populate *Index type* with either {ref}/geo-point.html[geo_point] or + {ref}/geo-shape.html[geo_shape] and *Index name* with +``. + +. Click *Import file* in the lower right. ++ +You'll see activity as the GeoJSON Upload utility creates a new index +and index pattern for the data set. When the process is complete, you should +receive messages that the creation of the new index and index pattern +were successful. + +. Click *Add layer* in the bottom right. + +. In *Layer settings*, adjust settings and <> as needed. +. Click *Save & close*. +. Once you've added all of the sample files, +<>. ++ +At this point, you could consider the map complete, +but there are a few additions and tweaks that you can make to tell a +better story with your data. ++ +[role="screenshot"] +image::maps/images/fu_gs_flight_paths.png[] + +[float] +=== Add a heatmap aggregation layer + +Looking at the `Lightning detected` layer, it's clear where lightning has +struck. What's less clear, is if there have been more lightning +strikes in some areas than others, in other words, where the lightning +hot spots are. An advantage of having indexed +{ref}/geo-point.html[geo_point] data for the +lightning strikes is that you can perform aggregations on the data. + +. Below the map legend, click *Add layer*. +. From the list of layer types, click *Grid aggregation*. ++ +Because you indexed `lightning_detected.geojson` using the index name and +pattern `lightning_detected`, that data is available as a {ref}/geo-point.html[geo_point] +aggregation. + +. Select `lightning_detected`. +. Click *Show as* and select `heat map`. +. Click *Add layer* to add the heat map layer +"Lightning intensity". ++ +The remaining default settings are good, but there are a couple of +settings that you might want to change. + +. Under *Source settings* > *Grid resolution*, select from the different heat map resolutions. ++ +The default "Coarse" looks +good, but feel free to select a different resolution. + +. Play around with the *Layer Style* > +*Color range* setting. ++ +Again the default looks good, but feel free to choose a +different color range. + +. When you're finished modifying settings, click *Save & close*. ++ +With your new lightning heat map layer, your map should look +like this: ++ +[role="screenshot"] +image::maps/images/fu_gs_lightning_intensity.png[] + + +[float] +=== Organize the layers + +Consider ways you might improve the appearance of the final map. +Small changes in how and when layers are shown can help tell a +better story with your data. Here are a few final tweaks +you might make: + +* Update layer names +* Adjust styles for each layer +* Adjust the layer order +* Decide which layers to show at different zoom levels + +When you've finished, again be sure to <>. + +Your final map might look like this: + +[role="screenshot"] +image::maps/images/fu_gs_final_map.png[]