User:DTankersley (WMF)/misc/how to: embedded maps

Let's add interactive maps for a richer experience using mapframe

This is a how-to guide for creating simple but beautiful maps that use OpenStreetMap data and Wikimedia tile images and are embedded within a page. We've recently created a method to add maps to articles and wanted to provide a step-by-step guide for new users. This new method is called mapframe and more detailed information about the Maps project can be found here.

Find an article to update with a map

Let’s find an article that the addition of the map would make it just that much richer in content, an easy article would be the city that you live in, or a notable location nearby. For purposes of this guide and for the easy map samples, we'll use the small but very scenic town of Estes Park located in the state of Colorado in the USA.

Easy map - more details

Find the coordinates (latitude and longitude) for your map

The article for Estes Park has coordinates (latitude and longitude) in the information section - 40°22′38″N 105°31′32″W - this makes it easy for us to add in a mapframe, in which to display an interactive map using Wikimedia tiles and map data from OSM.

If you click on the coordinates on the page, a new page is opened up that contains the GeoHack information for Estes Park. We’ll need to copy the coordinates that are in decimal degrees as displayed: 40.377117, -105.525514.

Add an embedded map to your page

Now that you know where you want to add a map and have the coordinates, it's time to have fun adding an embedded map to your articles or media.

Additional information about your interactive map

* Each map that is embedded on the page, when the map is clicked on, will open in a new tab (or window).

* The map that is displayed within the page is not interactive - it is a static image to allow for fast page loading.

* Once a user clicks on the map - it will be fully interactive; it can be zoomed in and out or panned to view different areas.

* Each interactive map will have a caption below the map that will contain (by default) the center of the map coordinates or custom text.

* There is a more details button that displays additional ways to display the map: satellite, topological, terrain, aerial or other external service providers (as available). The more details button is meant as a replacement for the GeoHack templated map service.

* Each map will have a attribute line with a link to the OpenStreetMap copyright and license as well as a link to the Wikimedia maps terms of use and licensing page.

* The interactive map can be closed by clicking the X in the top right hand corner of the map, clicking your browser's back button (if the map opened in your existing browser tab) or closing the tab (if the map opened in a new tab or window).

Easy embedded map samples

Just a map:

The easiest way to add a map for Estes Park is adding the following code in the page. This will display a static map that, when clicked, will open up map in your browser.

<mapframe latitude="40.377117" longitude="-105.525514" width="200" height="200"/>

A map with custom text and setting the zoom level for the map, once it's opened:

Let's now set a zoom level for the interactive map, since you might want to display your map closer into the city:

<mapframe latitude="40.377117" longitude="-105.525514" text="A custom zoom level map of Estes Park, CO" zoom="15" width="200" height="200" />

Cool but complex things you can do with a map

Add a custom icon marker, article link and image to your map:

<mapframe text="Colorado State Capital with a town hall marker, article link and image" latitude="39.73939" longitude="-104.98491" zoom="17" width="300" height="350">
{
      "type": "Feature",
      "properties": { "marker-symbol": "town-hall", "marker-color": "46ea5f", "marker-size": "medium", "title": "[[wikipedia:Colorado_State_Capitol|Colorado State Capital]]", "description": "[[File:Coloradocapitolhill2.JPG|150px]]"},
      "geometry": { "type": "Point", "coordinates": [-104.98485267162323, 39.73928364167763] }
}
</mapframe>

Add a Wikidata ID to highlight a state (geoshape):

<mapframe text="State of Colorado, outlined" zoom=7 width="200" height="200">
{ "type": "ExternalData", "service": "geoshape", "ids": "Q1261" } 
</mapframe>

Add a Wikidata ID to mask everything but a state (geomask):

<mapframe text="State of Colorado, highlighted" zoom=7 width="200" height="200">
{ "type": "ExternalData", "service": "geoshape", "ids": "Q1261", "service": "geomask" } 
</mapframe>

Add several map markers in different sizes using a feature collection:

<mapframe text="Denver Amusements" latitude="39.74956567318853" longitude="-105.01247406005858" zoom="14" width="300" height="350"> 
{
"type": "FeatureCollection", "features":  [
 { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-105.00768899917603, 39.74859230437501] }, 
"properties": { "title": "[[wikipedia:Pepsi_Center|Pepsi Center]]", "marker-color": "420617", "marker-symbol": "-letter-see", "marker-size":"small"} },
 { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-105.01238822937012, 39.7526011757416] }, 
"properties": { "title": "[[wikipedia:Downtown_Aquarium%2C_Denver|Downtown Aquarium Denver]]", "marker-color": "508e33", "marker-symbol": "-letter-see","marker-size":"medium", "description": "[[File:Denver-DTA.jpg|150px]]" } },
 { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-105.01247406005858, 39.74956567318853] }, 
"properties": { "title": "[[wikipedia:Confluence_Park|Confluence Park]]", "marker-color": "0d2751", "marker-symbol": "-letter-see", "marker-size":"large" } },
 { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-105.01646518707275, 39.74656303364532] }, 
"properties": { "title": "South Platte Bike Trail", "marker-color": "61b9e2", "marker-symbol": "-number-see", "marker-size":"medium" } },]
}
</mapframe>

Good things to know about using embedded maps

• Map zoom levels are between 0 (zero) and 18 (eighteen).
• Map markers can use any color that has a RBG value (a quick internet search of "rgb color picker" will show several options).
• Markers can be one of three different sizes: small, medium or large.
• All available speciality icons can be viewed at Maki Icons.
• If you are creating maps on Wikivoyage, it might be a good idea to use Groups.
• If you want to learn more about adding external data to your map, this is a good place to start.

Important notes

• Embedded maps are currently only available on certain projects - MediaWiki and WikiVoyage.
• Embedded maps are currently only available on Russian, Hebrew and Catalan Wikipedias.
• When using mapframe, there will always be a static map image in the article page
  • Clicking on the static map image will open up the interactive map in your existing tab, or - right click on the map image and open in a new tab or window.

See also

• Click here for step-by-step instructions on adding a map link to your page
• Click here for instructions on adding a map using Visual Editor and the Map template
• Click here for more information on the Discovery Maps project
• Click here to find out more about Kartographer
• Click here to find our more about the tile server implementation (Kartotherian)
• Terms of use and where the map data comes from
• How to use dynamic maps on Wikivoyage