Wikivoyage:How to use dynamic maps

See also: Wikivoyage:How to draw static maps, Wikivoyage:Dynamic maps Expedition

Need a map that will dynamically update as listings are added, updated and removed? This page tells how.

Embed a dynamic map

Map of How to use dynamic maps

Place the {{Mapframe}} template at the point on the page where you wish the embedded map to appear. It will display on the right side of the page by default. It should usually be placed right underneath the "Get around" heading so that it is not too far from subsequent listings.

The syntax is

{{Mapframe|latitude |longitude |zoom=zz |height=nnn |width=nnn |staticmap=image file |align=align}}

Some remarks

latitude is the decimal latitude co-ordinate ( 2 to 5 decimal places ) e.g. 6.78 or 23.54321
longitude is the decimal longitude co-ordinate ( 2 to 5 decimal places )

do not put the words lat= and long= before the co-ordinates as you would in a listing template, because it doesn't work in Mapframe

zz is a number between 1 and 18 that specifies the enlargement or zoom level at which the map is initially displayed on the page (this can then be adjusted by the reader). A zoom level of 13 to 15 is often appropriate for maps of settlements. Optional - default is 14.

If (lat, long) and zoom are omitted, {{mapframe}} alone will now default to a scale and position that fits all of the current article's POIs onto the map. These defaults are usually adequate.

nnn is the width and height in pixels that the embedded map will display at on the page. Optional - default is 420px for both height and width.
image file is optional and is the file name of a normal png or svg file for a static map image. Optional - if specified, a hyperlink with the text "View static map" is displayed at the lower corner of the map frame.
align is the alignment of the map frame. Optional - default is right aligned (other values are "left" and "none" (center)).
group is one additional parameter which may specify which markers (listing, see, do, buy, eat, drink, sleep) to be displayed on the map.
name is another additional parameter to define a non-default caption below the map. This is often helpful to remove disambiguators in titles.

Incrementally numbered, coloured icons will appear automatically on the embedded dynamic map as Points of Interest (PoI) for each listing in the article that has both lat and long attributes set.

Map not detailed enough?

Maybe the area where you're trying to add a map doesn't have enough details, with a single solitary main road compared to the dozens in reality. This means that the base map data just isn't enough, and you'll have to head over to OpenStreetMap and use their iD editor or another editor like JOSM. To add roads and buildings, trace over satellite images. If the roads are unnamed, name them.

If you don't feel up to it, ask at Wikivoyage:Dynamic maps Expedition or Wikivoyage:Requests for maps, and someone may come along and add the details to OpenStreetMap instead.

Geo template

You might have noticed a small map icon at the top of the screen, which links to a large map of the area an article covers. Not there? Use GeoMap and select the Geo option at the left side to fill out the {{geo}} template which might look like {{geo|1.3421|129.0122|zoom=14}}. The numbers mark the centre of the city or region, while the zoom number determines the scale of the map. 1 covers the entire earth, and 18 marks the city block level.

Adding images

There's an additional image attribute that can be added to a listing so that the tiny image pops up on the dynamic map when a PoI is clicked. This preview image can be enlarged by clicking.

Syntax: image=filename

Examples:
{{listing | name=Tourismus-Amt | ..... | image=Hornburg Tourismus-Amt.jpg | ..... }}

{{see | name=Old Faithful | ..... | image=Old Faithful Rainbow.jpg | ..... }}
.... = other parameters: | lat= | long= | etc | etc

Where do I put the dynamic map?

Put it right underneath the "Get around" heading.

If it's placed there, folks using the mobile version of Wikivoyage (which opens with all sections collapsed, apart from the lede paragraphs) will know which section to click on to open the dynamic map. If for some reason it is added to a different location, explain the reasoning in an edit comment or on the article's talk page.

Geocoding listings

What do all these numbers mean?

Wikivoyage uses the decimal degrees system for geographical co-ordinates. Each listing needs a unique pair of numbers, called latitude and longitude, which represent its location on a map. They are also known as geodata, co-ordinates, coords, or in short form, lat and long. Adding coordinates to points of interest is called geocoding.

Latitude refers to the north-south aspect, ranging from -90.00000° to 90.00000°. Negative latitudes are in the southern hemisphere, and those positively numbered are north of the equator.
Longitude specifies if the location is either east or west of the Prime Meridian at 0.00000° passing from the North Pole to the South Pole (through Greenwich, England) in the range from -180.00000° (west) to 180.00000° (east).

What about the decimal places? They measure the accuracy of the coordinates, i.e. how much error that is expected. Two decimal places means that it is accurate up to 500m to 1km (depending on how far north/south of the equator you are), which means you might actually be 250 to 500m away from where you want to be! Five decimal places reduces that error to about 1m, so more than 6 decimal places is almost certainly overkill. Each pair of latitude and longitude must have the same number of decimal places, even if that requires trailing zeroes.

Gather geo coordinates

Geodata is subject to copyright terms just like any data, so personal geodata and OpenStreetMap (OSM) coordinates are preferred over all other derivative sources. If possible, state your sources.

The most convenient tools for Wikivoyagers are GeoMap, which provides a very quick and easy way to get coordinates for one location, and Geobatcher, which provides a method to look up and hone in on coordinates for an entire Wikivoyage article at once, without ever needing to type or copy-paste the coordinates themselves!

Each listing has a separate icon depending on its type. Specific listing templates like See, Do, Buy, Eat and Sleep should only be used in their sections. For other sections like Get in and Cope, use the general {{listing}} template.

43.28694-78.191331 See. Example for a See listing.
43.28698-78.192111 Eat. Example for an Eat listing.
43.28798-78.193111 Sleep. Example for a Sleep listing.
43.28748-78.191951 Listing. Example for a General listing.

The automatic numbering in each section starts with "1". Exception to the general listing template, which is numbered throughout the article.

Method 1: GPS

Go to the place with a GPS or smartphone, and add the listing in this format: lat=12.34567 | long=45.67890

Method 2: Dynamic Map

If the location of a POI is known, open the poimap2 by clicking the map icon at the upper-right of a destination page, then right-click on the specific place in the dynamic map. A pop-up will open with the coordinates. Copy and paste this data into the appropriate listing.

Method 3: GeoMap

Open GeoMap. Fill in an address eg. 33, Long Row, Nottingham or Wall Street Bar, Roppongi. The search is multilingual, but is limited to OSM recognized terms. Click on the red marker. Then transfer the values displayed with copy & paste to the article.

Method 4: Geobatcher

Use Geobatcher to find and map up to 100 coordinates at a time.

Enter the city and/or country in the first field.
Choose to search by either Name or Address. Searching by name matches OpenStreetMap's Points of Interest database, while searching by address relies on block addresses which may have gaps (eg cannot find 20 Main St between 1 Main St and 50 Main St).
From the Wikivoyage article's Edit tab, copy-paste the listings into the large text field.
Press the Find coords button. 1 listing generally takes 1 second to find.
Listings whose coordinates have been found are mapped, and those without coordinates are marked with a question mark on the map.
Drag and drop the markers to adjust the coordinates. If you don't know where the other listings are, press the Remove ?s button.
lat/long attributes have been inserted in the third text field.
Copy the listings of the third text field back to Wikivoyage.

Bonus: Search OSM using the textbox above the map, and the returned coordinates are listed and mapped with the red marker.

Method 5: ShareMap

ShareMap.org - open, creative commons, social mapping tool (http://sharemap.org) can be used to generate entire list of POI's for some article. With ShareMap user can easily use search services (Nominatim), import OSM data (wizard or XAPI queries) or even calibrate old raster maps (please be careful the create content on CC licenses)

Detailed tutorial screencast can be found here - http://www.youtube.com/watch?v=Xc5F98q87uo

Method 6: OSM

Search for your listing on OpenSteetMap. Then right-click it and select "show address". This will show lat/long in the left panel (2nd line). Also "Query features" can be used to get locations of the individual POIs.

Method 7: Google Maps

Please avoid using this method if possible as it would introduce a lot of licensing issues when collaborating with OpenStreetMap. If this method is used, be sure to name Google Maps as the source of the coordinates in your edit summary.

Open Google Maps and right click on the location you would like to fetch. The coordinates will show up on the very top of the pop-up menu. Click on it to copy the values.

Converting from DMS system

To convert from a traditional Degrees/minutes/seconds format like lat=N45°30'0", long=W73°36'0", use the following formula:

X°Y'Z" = X+(Y/60)+(Z/3600)
- for S, add "-" to lat; for N, assume "+"
- for W, add "-" to long; for E, assume "+"

Adding districts and tracks

Example of custom districts and a OpenStreetMap track for Singapore

Districts can be useful to highlight different zones on the map, whereas tracks can show hiking trails or other elements, which could be relevant for travellers (e.g. the outline of the F1 track in Monaco).

OpenStreetMap districts and tracks

The preferred method for adding districts is to use already existing geometry from the OpenStreetMap database to render a mask, shape or line. See the {{mapshape}} template documentation for further details.

Below are two examples. Explanation of the code:

The first line adds the map to the article. Coordinates of map center, size of the map on the page and zoom level have been defined.
The second line pulls the districts/track from OpenStreetMap with help of the appropriate Wikidata-ID. A title has been defined, which appears after clicking on the map element.

Example 1 - Hiking trail

Live example as shown on the article map: Southern Ridges Walk

{{mapframe|1.28278|103.79203|width=450|height=300|zoom=13}}
{{Mapshape|type=geoline|wikidata=Q7570434|fill=#FF0000|stroke-width=3|title=Southern Ridges Walk}}

Example 2 - District boundary

Live example as shown on the article map: Hamburg districts

{{Mapframe|width=450|height=450|53.560|10.023|zoom=10|show=go,mask}}
{{Mapshape|type=geoshape|wikidata=Q1554, Q1551, Q1561|fill=#d5dc76|title=[[Hamburg/Neustadt-Altstadt|Neustadt-Altstadt]]}}

The tool Wikivoyage Districtifier might be able to support you in the creation of district overview maps.

Custom districts and tracks

There are two very handy use-cases for self-made GeoJSON files in maps:

You would like to add a hiking route or similar itinerary based elements, which are not available in OpenStreetMap (Example: Stockholm history tour).
The official district boundaries are non-existent in OSM or they simply don't make much sense from a tourist perspective. (Example: Singapore or Amsterdam).

If you are looking for a simpler way compared to the video below for itineraries, see User:SHB2000/Getting a line on an itinerary, where the GeoJSON code is copied right into the article. It can also be used for hiking routes too.

Creating GeoJSON data

The video below shows how to create a dynamic district overview map with custom-made district boundaries. The same workflow applies for routes by drawing lines instead of polygons.

Create GeoJSON with JOSM and upload to Wikimedia Commons. High-Res video available on YouTube

Workflow

The text below is meant to be additional information to the video. The video should be watched to get a real understanding of the workflow.

1. Create district overview map

In short there are two options to create the GeoJSON:

1a. geojson.io only

Go to geojson.io, draw the lines/polygons, give them the desired color and title. Copy the GeoJSON file and proceed to step 2. A certain disadvantage with this solution is, that you cannot merge nodes. So if you have 2 polygons right next to each other, they won't be perfectly aligned. With the solution in 1b this problem is nonexistent.

1b. JOSM & geojson.io (shown in the video)

Use JOSM to draw polygons as desired and export as .geojson. Some notes:

The export of polygons to .geojson only works as expected in JOSM, if the polygons have a describing tag assigned to them, which is usually applied to an area in OpenStreetMap (e.g. landuse=residential).
You can assign the title and fill tags to each polygon/line right in JOSM, if you don't want to do it in geojson.io (e.g. title=[[Amsterdam/Noord|Noord]] and fill=#000000).

2. Upload to Commons

Create a new map in Wikimedia Commons and paste in the GeoJSON created in 1.

3. Create article map in Wikivoyage with link to the GeoJSON file saved in Commons

Example:

{{Mapframe|55.95878|-3.18726|width=600|height=550|zoom=13}}

and

{{Mapshape|type=page|wikicommons=Edinburgh_Districts.map}}

4. Create mapmasks (optional)

In order to grey out the irrelevant parts of a district article map (example) you can paste the GeoJSON from 2. into the tool Mapmask <-> GeoJSON Converter to create the mapmask code.

Creating GPX data

As an alternative to directly create GeoJSON as described above it is also possible to generate a GPX track and subsequently convert it to GeoJSON. To create a mapmask - the boundaries that designate a district (example) - or GPX tracks for an itinerary (example) then the following steps are necessary:

Generate the boundary or track data
Option #1: Download the data directly from OpenStreetMap.org:
1. Download JOSM, which is an editor for OpenStreetMap data.
2. Find the boundary or route object in OpenStreetMap that you are interested in. For example, if looking for city boundaries:
  1. Navigate to the desired city on openstreetmap.org
  2. Click on the "?" icon to query features.
  3. Click on the map at a point you are interested in (for example, the city name if generating city boundaries).
  4. After clicking, a list of "enclosing features" will appear in the left nav. Select the feature you are interested in (example: "City boundary city name")
  5. You should then see a view of the selected object, and the left nav will show the boundary type and ID, for example "Relation: city name (id)" - remember these values as they will be used in the next step.
3. In JOSM, go to File → Download Object. Enter the object type and ID that you found on OpenStreetmap. JOSM will then display the object.
4. Edit the object in JOSM as needed - for example, if there are extraneous objects they can be deleted. In most cases this step should not be necessary.
5. In JOSM go to File → Save As, choose "GPX files" as the file type, and use any file name you like.
Option #2: Create a trace yourself:
1. Use an appropriate route editor. Do not use Google Maps to trace a boundary/track - Google maps licensing is incompatible with the OSM license.
2. Create a track by clicking the map at different points. Save as mytrack [TRACK].
Go to the Wikivoyage GPX formatter tool and upload the GPX file you just created. This tool will reformat the information into a format that can be consumed by the Wikivoyage map tools. Verify that the map preview shown at the bottom of the page after submitting matches what you expect. If the map is not what you expect you will need to modify the GPX data. If you are not sure what needs to be done ask for help from other Wikivoyage users.

Various third-party utilities may be used to generate GPX traces, which may then be converted to GeoJSON for use in Wikivoyage:

GPX online editor. See online help for instructions. Download as a track.
http://gpxcreator.com is a free, open-source Java desktop app which displays an OpenStreetMap and allows a user to trace a path, generating a GPX file. Only minor changes (such as a text editor search-and-replace to remove "elevation=0" from each point) are needed to convert these paths into usable format for itineraries.
OpenStreetMap provides JOSM as a utility to generate GPX traces, see http://josm.openstreetmap.de/download/josm.jnlp

Conversion to GeoJSON

Various online utilities convert GPX or other standard formats to GeoJSON, for example:

Once the track or boundary is in a compatible format, various options allow its use in Wikivoyage:

A boundary may be used with the {{mapmask}}, {{mapshape}} and {{mapframe}} templates.
A boundary or track may be used directly, as described in mw:Help:Extension:Kartographer.

See Trans-Siberian Railway for an example of a direct call to <maplink> to draw an itinerary across Russia. The <maplink> co-ordinates are in the article, at the end of the page.

See St. Petersburg for an example of Commons as a data source, data from commons:Data:Saint_Petersburg_Districts.map is transcluded with:

{{Mapframe|59.92|30.24|30.30|zoom=9|show=other,mask,go}}
{{mapshape|type=page|wikicommons=Saint_Petersburg_Districts.map}}

The {{GPX}} template subpages are now deprecated. User:Yurik/Sandbox/Gpx1 and User:Yurik/Sandbox/Gpx2 contain converted versions of the existing GPX traces which were already in Wikivoyage at the time mw:Extension:Kartographer was deployed. These may be imported back to the original articles by removing the (lat, long, zoom) parameters - allowing the new {{mapframe}} to autodetect the correct scale and extents. Special:Diff/3142916/3207633 is an import of one of these maps onto Trans-Labrador Highway, for example. (See also phab:T154908 and phab:T137677.)