__EXPECTED_UNCONNECTED_PAGE__

This template adds a link, or frame, which will display a map from OpenStreetMap together with specified map data. The map and data can be viewed in a scrollable and zoomable fullscreen window. The map data can come from:

• data stored in GeoJSON format on Wikipedia or Commons
• line/polygon features in OpenStreetMap.
• coordinates, either supplied or from Wikidata
• raw GeoJSON, preferably transcluded from another page

Note:

• If you have a very large/slow map, you should use the mapframe extension tag directly instead of this template, as was done in Special:Diff/970846012. The reason for this is that using the template to call the extension tag will result in the map rendering counting as Lua time, which may result in time exceeded errors.
• GeoJSON files cannot currently be directly uploaded. Instead, on Commons, create a page that is in the Data: namespace and ends in .map – see mw:Help:Map Data for further information.
• To make OpenStreetMap (OSM) features available, add the Wikidata key to the OSM relation (and wait 1 or 2 days) – see mw:Help:Extension:Kartographer#External_data, mw:Help:Extension:Kartographer/OSM and Module talk:mapframe/FAQ for further information.

Uses

This template is intended to show points as well as linear or polygon features on a map, including (but not limited to):

• Roads
• Rivers
• Subway or train lines
• Ship courses
• Flight paths
• Explorers journeys
• Animal habitats
• Countries and their subdivisions

and more... This template can also be used to display point features on a map, i.e. coordinates.

Usage

Basic usage

• <maplink text="Data page">{"properties":{"stroke-width":6,"stroke":"#ff0000","title":"Maplink/doc"},"type":"ExternalData","title":"ecos.fws.gov/Endangered habitat 58938/Plethodon neomexicanus.map","service":"page"}</maplink> on Commons (e.g. Data:ecos.fws.gov/Endangered habitat 58938/Plethodon neomexicanus.map):

  {{maplink|from=}} (specify .map data page in from=, excluding Data prefix)

• <maplink text="Raw GeoJSON data">{{Wikipedia:Map data/Main Roads Western Australia/Forrest Highway}}</maplink> (e.g. Wikipedia:Map data/Main Roads Western Australia/Forrest Highway):

  {{maplink|raw=}} (specify raw GeoJSON, preferably transcluded from a subpage of Wikipedia:Map data)

• <maplink text="Line of a border or a linear feature">{"properties":{"stroke-width":6,"stroke":"#ff0000","title":"Maplink/doc"},"type":"ExternalData","service":"geoline","ids":"Lua error in Module:WikidataIB at line 3438: attempt to index field 'wikibase' (a nil value)."}</maplink> from OSM:

  {{maplink|type=line|id=}} (Wikidata id only required if another article's Wikidata page is to be used)

• <maplink text="Shape">{"properties":{"stroke-width":6,"stroke":"#ff0000","title":"Maplink/doc"},"type":"ExternalData","service":"geoshape","ids":"Lua error in Module:WikidataIB at line 3438: attempt to index field 'wikibase' (a nil value)."}</maplink> from OSM:

  {{maplink|type=shape|id=}} (Wikidata id only required if another article's Wikidata page is to be used)

• <maplink text="Inverted shape">{"properties":{"stroke-width":6,"stroke":"#ff0000","title":"Maplink/doc"},"type":"ExternalData","service":"geomask","ids":"Lua error in Module:WikidataIB at line 3438: attempt to index field 'wikibase' (a nil value)."}</maplink> from OSM:

  {{maplink|type=shape-inverse|id=}} (Wikidata id only required if another article's Wikidata page is to be used)

• (coordinates):

  ...from Wikidata:
  {{maplink|type=point|id=}} (Wikidata id only required if another article's Wikidata page is to be used)

  ...from specified coordinates:
  {{maplink|type=point|coord=}} (specify coordinates using {{Coord}} template)

• from a page or section ({{coord}} templates using the <syntaxhighlight lang="wikitext" inline style="display: none;" />|name= parameter)

  ...from the current page: {{maplink|type=named}} or {{maplink|type=named|from=#Section}}

  ...from another page: {{maplink|type=named|from=Other page}} or {{maplink|type=named|from=Other page#Section}}

• (centred on a point's coordinates):

  ...from Wikidata:
  {{maplink|type=circle|radius=|id=}} (Wikidata id only required if another article's Wikidata page is to be used)

  ...from specified coordinates:
  {{maplink|type=circle|radius=|coord=}} (specify coordinates using {{Coord}} template)

• To show in a frame, add the parameter <syntaxhighlight lang="wikitext" inline style="display: none;" />|frame=yes: {{maplink|frame=yes|frame-align=left|type=line|id=Q1094308|text=Mapframe example}}.
  <mapframe height="200" text="Mapframe example" align="left" width="300">{"properties":{"stroke-width":6,"stroke":"#ff0000","title":"Maplink/doc"},"type":"ExternalData","service":"geoline","ids":"Q1094308"}</mapframe>

• Additional parameters are available to customise the displayed map, such as <syntaxhighlight lang="wikitext" inline style="display: none;" />|plain=yes to remove the outer frame: {{maplink|frame=yes|frame-align=left|plain=yes|type=line|id={{get QID|Várkerület}}|frame-width=200|frame-height=250|frame-long=19.1009|frame-lat=47.5001|zoom=9}}.
  <mapframe zoom="9" frameless="1" align="left" height="250" latitude="47.5001" longitude="19.1009" width="200">{"properties":{"stroke-width":6,"stroke":"#ff0000","title":"Maplink/doc"},"type":"ExternalData","service":"geoline","ids":"Lua error in Module:WikidataIB at line 3438: attempt to index field 'wikibase' (a nil value)."}</mapframe>

Parameter set – data page <syntaxhighlight lang="wikitext"> <maplink text="Map">[

]</maplink> </syntaxhighlight>

Parameter set – raw data <syntaxhighlight lang="wikitext"> <maplink text="Map">[

]</maplink> </syntaxhighlight>

Parameter set – geoline/geoshape <syntaxhighlight lang="wikitext"> <maplink text="Map">[

]</maplink> </syntaxhighlight>

Parameter set – point features/coordinates <syntaxhighlight lang="wikitext"> </syntaxhighlight>

Parameter set – circles <syntaxhighlight lang="wikitext"> </syntaxhighlight>

Parameters

For overall display

display

How the template is displayed. Valid values are:

inline - Only displays the inline link (you can forego this, as it is the default)

title - Only displays the title link

inline,title - Displays the inline link as well as the title link

title,inline - Same as above

text

Text to display for the link (or caption if using mapframe); default is "Map"

icon

Set to "no" to turn off the icon that appears next to the link

zoom

Zoom level, from 1 to 19 (larger numbers zoom in further); default is automatically determined by the map, unless the only feature is a single point.

Mapframe parameters (only work with inline display)

frame

Set to "yes" to show a map frame instead of a link

plain

Set to "yes" to show just the map without the surrounding frame, and without a caption (text parameter will be ignored)

frame-align

Alignment with respect to the page: left, center, or right; default is right

frame-width

Width of the map frame in pixels, default is 300

frame-height

Height of the map frame in pixels, default is 200

frame-coordinates

(or frame-coord)

Optional - coordinates of the center of the map. Use {{Coord}} template to specify coordinates (e.g. <syntaxhighlight lang="wikitext" inline style="display: none;" />|frame-coordinates=<syntaxhighlight lang="wikitext" inline></syntaxhighlight>). If not set, coordinates will be retrieved from Wikidata.

frame-latitude

(or frame-lat)

(ignored if <syntaxhighlight lang="wikitext" inline style="display: none;" />|frame-coordinates= or <syntaxhighlight lang="wikitext" inline style="display: none;" />|frame-coord= is set)

Optional - latitude coordinate for center of the map.

frame-longitude

(or frame-long)

(ignored if <syntaxhighlight lang="wikitext" inline style="display: none;" />|frame-coordinates= or <syntaxhighlight lang="wikitext" inline style="display: none;" />|frame-coord= is set)

Optional - longitude coordinate for center of the map.

Note: If frame latitude and longitude are not set by parameters, then frame coordinates can be determined automatically, either:

• Based on the line and shape objects (if any have been specified), or
• From the point feature specified in <syntaxhighlight lang="wikitext" inline style="display: none;" />|coord= (if set), or
• Retrieved from Wikidata (if available – for either the item specified in <syntaxhighlight lang="wikitext" inline style="display: none;" />|id= parameter, or for the page the template is placed on)

overlay

An image, or another map, to be displayed on top the map. E.g.

<syntaxhighlight lang="wikitext" inline style="display: none;" />|overlay=[[File:Example.svg|140x140px]] or

<syntaxhighlight lang="wikitext" inline style="display: none;" />|overlay= or

<syntaxhighlight lang="wikitext" inline style="display: none;" />|overlay=

(see Template:Maplink/testcases/overlays to view examples)

overlay-horizontal-alignment

Horizontal alignment of overlay, either left or right; default is right

overlay-vertical-alignment

Vertical alignment of overlay, either top or bottom; default is bottom

overlay-horizontal-offset and overlay-vertical-offset

Optional – number of pixels to offset the overlay in from the edge of the map, e.g. 10 for a 10 pixel gap

overlay-border

CSS style for the border, e.g. 3px solid black; default is 1px solid white. The colour can be any web color name or hex code.

Raw GeoJSON

raw

Raw GeoJSON as well as <maplink> functionality is not available via the other parameters, see below for more information. Raw GeoJSON can be transcluded from Commons (.map files, see Help:Map data) or Wikipedia (preferably transcluded from a subpage of Wikipedia:Map data).

For each feature

Multiple features can be displayed on a single map. For each additional feature, add a sequential number to the end of the parameter name. For example, the second uses parameters like <syntaxhighlight lang="wikitext" inline style="display: none;" />|type2=, <syntaxhighlight lang="wikitext" inline style="display: none;" />|id2=, etc., the third feature <syntaxhighlight lang="wikitext" inline style="display: none;" />|type3=, <syntaxhighlight lang="wikitext" inline style="display: none;" />|id3=, etc., and so on. Higher numbers are drawn on top.

type

Type of data. Valid values are:

line – a geoline feature from OSM (e.g. a road)

shape – a geoshape feature from OSM (e.g. a state or province)

shape-inverse – a geomask feature from OSM (the inverse of a geoshape - allows an unobstructed view of the map beneath)

data – a geoJSON data page on Commons (parameter is optional in this case)

point – a point feature (coordinates)

named – all named coordinates in an page or section ({{coord}} templates with <syntaxhighlight lang="wikitext" inline style="display: none;" />|name= parameter)

circle – a circle centred on a point's coordinates

id

(or ids)

Wikidata id (Q-number) of the point feature, Wikidata id that the OSM line/shape feature is tagged with. Separate multiple ids with a comma. Defaults to the current page's Wikidata id (if <syntaxhighlight lang="wikitext" inline style="display: none;" />|from= not set).

from

Source of map data:

• If type is data or omitted: The JSON (.map) file from Commons to display (excluding the Data: prefix)
• If type is named: Page name, or name#section, to get named coordinates from. If omitted, or specified as just #section, then current page will be used.

title

Title of the feature (for features from OSM), displayed when the feature is clicked on; default is the page title

description

Description of the feature (for features from OSM), displayed when the feature is clicked on; optional

stroke-color

(or stroke-colour)

Color code for the color used to draw the feature (for features from OSM); default is #ff0000 (red)

stroke-width

Width for the lines used to draw the feature (for features from OSM); default is 6

stroke-opacity

Opacity for the lines used to draw the feature (for features from OSM) – a number between 0 (fully transparent) and 1 (fully opaque); default is 1

fill

Color code for the fill color of the feature (for shape or shape-inverse features from OSM); default is #000000 (black). Note that a semi-transparent version of the specified color will be used by default, allowing the map below to still be seen.

fill-opacity

Opacity for the fill color of the feature (for shape or shape-inverse features from OSM) – a number between 0 (fully transparent) and 1 (fully opaque); default is 0.5

coord

Coordinates to display for a point feature. Use {{Coord}} template to specify coordinates (e.g. <syntaxhighlight lang="wikitext" inline style="display: none;" />|coord={{Coord|12.34|S|56.78|W}}). If not set, coordinates will be retrieved from Wikidata.

marker

Name of Maki marker image to display at the point feature. See mw:Maps/Icons for options. If not set, a plain marker will be shown without an image.

marker-color

(or marker-colour)

Color code (Hex triplet) specifying marker background color. Default is 5E74F3 ( )

marker-size

Size of the marker. Can be small, medium (default) or large.

radius

(or radius_m), or alternative parameters radius_km, or radius_mi, or radius_ft

Radius of the circle. In metres by default, or in kilometers or miles or feet if the alternative parameters are used.

edges

Number of edges used to construct the circle. Default is 32. Higher numbers will result in a smoother circle but use more Lua processing resources.

TemplateData

This is the TemplateData for this template used by TemplateWizard, VisualEditor and other tools. See a monthly parameter usage report for Template:Maplink in articles based on its TemplateData.

TemplateData for Maplink

<templatedata> { "params": { "display": { "description": "How the template is displayed", "suggestedvalues": [ "inline", "title", "inline,title" ], "default": "inline" }, "text": { "description": "Text to display for the link (or caption if using mapframe)", "type": "line", "default": "Map" }, "icon": { "description": "Set to \"no\" to turn off the icon that appears next to the link", "type": "boolean" }, "zoom": { "description": "Zoom level, from 1 to 19 (larger numbers zoom in further); default is automatically determined by the map, unless the only feature is a single point.", "type": "number" } }, "description": "Adds a link, or frame, which will display map data" } </templatedata>

Multiple map switcher

An option for Template:Switcher-style switching of multiple mapframes, where specified parameters like zoom, or frame coordinates, or a shape's item id are switched between different values. When using, ensure the number of values in each list are the same.

Instructions:

1. Add parameter switch to specify labels for the different options: a list separated by either<syntaxhighlight lang="text" class="" style="" inline="1">,</syntaxhighlight>, or <syntaxhighlight lang="text" class="" style="" inline="1">;</syntaxhighlight> if the labels contain commas, or <syntaxhighlight lang="text" class="" style="" inline="1">###</syntaxhighlight> if the labels contain semi-colons. Each label will be displayed with a prefix of "Show ".

   Example: <syntaxhighlight lang="wikitext" inline style="display: none;" />|switch=zoomed out, zoomed mid, zoomed in

2. For each parameter that is to be switched, set its value to SWITCH: followed by a list of values to switch between, again separated by <syntaxhighlight lang="text" class="" style="" inline="1">,</syntaxhighlight> or <syntaxhighlight lang="text" class="" style="" inline="1">;</syntaxhighlight> or <syntaxhighlight lang="text" class="" style="" inline="1">###</syntaxhighlight>

   Example: <syntaxhighlight lang="wikitext" inline style="display: none;" />|zoom=SWITCH:4,9,14

   Parameters frame, plain, and text should not be switched

3. Make sure each list has the same number of entries. The position of value in a SWITCH: list corresponds to the same position in the list of labels set in <syntaxhighlight lang="wikitext" inline style="display: none;" />|switch=.

Example: <syntaxhighlight lang="wikitext"></syntaxhighlight>

Examples and tips

Multiple features

Multiple features allow you to:

• Use external data from both Wikimedia Commons and OpenStreetMap together
• Apply different styles to different external data features from OpenStreetMap
• Include multiple links to external data from Wikimedia Commons

<syntaxhighlight lang="wikitext"> </syntaxhighlight>

<syntaxhighlight lang="wikitext"> </syntaxhighlight>

Infoboxes

Mapframes can be included in infoboxes. Using <syntaxhighlight lang="wikitext" inline style="display: none;" />|plain=yes to remove the outer frame is recommended.

For simple cases with a single feature, {{infobox mapframe}} can be used instead (see that template's documentation for details).

Mitchell Freeway
<mapframe zoom="9" frameless="1" align="center" height="200" latitude="-31.8262" longitude="115.7877" width="300">{"properties":{"stroke-width":6,"stroke":"#ff0000","title":"Maplink/doc"},"type":"ExternalData","service":"geoline","ids":"Q1939502"}</mapframe>
Map of Perth's northern suburbs with Mitchell Freeway highlighted in red
Type	Freeway

<syntaxhighlight lang="wikitext">

... (other parameters omitted) ...

</syntaxhighlight>

The raw parameter

The "raw" parameter allows the same inputs as the full <maplink> function. It allows you to:

• Use GeoJSON data directly
• Use Wikidata queries to obtain information for the map
• Use templates - if a map includes direct GeoJSON or many components, placing the data in a template will avoid cluttering the article text

See mw:Help:Extension:Kartographer for instructions.

Raw GeoJSON example

<maplink text="Route map">{{Wikipedia:Map data/Main Roads Western Australia/Forrest Highway}}</maplink> <syntaxhighlight lang="wikitext"> <maplink text="Route map">{{Wikipedia:Map data/Main Roads Western Australia/Forrest Highway}}</maplink> </syntaxhighlight> (Link to GeoJSON data subpage: Wikipedia:Map data/Main Roads Western Australia/Forrest Highway)

Raw Wikidata query examples

<mapframe zoom="1" text="Ten countries" height="400" latitude="25" longitude="10" width="600">{ "type": "ExternalData", "service": "geoshape", "query": " SELECT * WHERE { ?id wdt:P463 wd:Q1065 . } LIMIT 10 "}</mapframe> <syntaxhighlight lang="sparql" style="min-width:30em"> <mapframe zoom="1" text="Ten countries" height="400" latitude="25" longitude="10" width="600">{ "type": "ExternalData", "service": "geoshape", "query": " SELECT * WHERE { ?id wdt:P463 wd:Q1065 . } LIMIT 10 "}</mapframe> </syntaxhighlight>

<mapframe zoom="3" text="Map" height="400" latitude="52" longitude="-110" width="600">{ "type": "ExternalData", "service": "geoshape", "query": " SELECT ?id ?head (SAMPLE(?img) as ?img_) (min(?partyId) as ?party) (if(?party = '0', '#800000', if(?party = '1', '#000080', '#008000')) as ?fill) (concat('', ?headLabel, '') as ?title) (concat(?stateLabel, '\\n', 'File:', substr(str(?img ), 52, 500), '') as ?description) WHERE { ?id wdt:P31 wd:Q35657 . ?id wdt:P6 ?head . ?head wdt:P102 ?party . BIND(if(?party = wd:Q29468, '0', if(?party = wd:Q29552, '1', '2')) as ?partyId) SERVICE wikibase:label { bd:serviceParam wikibase:language 'en' . ?head rdfs:label ?headLabel . ?id rdfs:label ?stateLabel . } OPTIONAL { ?head wdt:P18 ?img . } ?link schema:about ?head . ?link schema:isPartOf <https://en.wikipedia.org/> . } GROUP BY ?id ?head ?headLabel ?link ?stateLabel "}</mapframe> <syntaxhighlight lang="sparql" style="min-width:30em"> <mapframe zoom="3" text="Map" height="400" latitude="52" longitude="-110" width="600">{ "type": "ExternalData", "service": "geoshape", "query": " SELECT ?id ?head (SAMPLE(?img) as ?img_) (min(?partyId) as ?party) (if(?party = '0', '#800000', if(?party = '1', '#000080', '#008000')) as ?fill) (concat('', ?headLabel, '') as ?title) (concat(?stateLabel, '\\n', 'File:', substr(str(?img ), 52, 500), '') as ?description) WHERE { ?id wdt:P31 wd:Q35657 . ?id wdt:P6 ?head . ?head wdt:P102 ?party . BIND(if(?party = wd:Q29468, '0', if(?party = wd:Q29552, '1', '2')) as ?partyId) SERVICE wikibase:label { bd:serviceParam wikibase:language 'en' . ?head rdfs:label ?headLabel . ?id rdfs:label ?stateLabel . } OPTIONAL { ?head wdt:P18 ?img . } ?link schema:about ?head . ?link schema:isPartOf <https://en.wikipedia.org/> . } GROUP BY ?id ?head ?headLabel ?link ?stateLabel "}</mapframe> </syntaxhighlight>

Gotchas

• When retrieving lines or shapes from OSM, you can't style the fill color or the opacity level of fills or strokes (unless you use the <syntaxhighlight lang="wikitext" inline style="display: none;" />|raw= parameter)
• The following code utilising the <syntaxhighlight lang="wikitext" inline style="display: none;" />|raw= parameter won't work because the curly brace to close the GeoJSON is adjacent to the curly braces to close the template: <syntaxhighlight lang="wikitext"><maplink text="Map">{"type": "ExternalData","service": "geoshape","ids": "Q13518258"</maplink>}</syntaxhighlight> To fix it, put a space before the two template braces or move them to a separate line.

Tutorials

• Wikipedia:Creating route maps from OpenStreetMap data
• Wikipedia:Creating shape maps from OpenStreetMap data

FAQ

Q1: Where to file a bug report when there is a problem with the base map? (e.g. a missing lake)

A1: If the problem also occurs on OpenStreetMap, it needs to be fixed there. If the problem is only on Wikimedia's maps, it can be reported on Phabricator (you can log in with you Wikipedia account). See mw:How to report a bug for instructions (for the tags, use Maps). (Alternatively, you can try mw:Help talk:Extension:Kartographer)

Q2: Where to report other bugs or problems with the maps?

A2: This may be a problem with the Wikipedia module, or it may be an underlying software bug (there are lots of those).

• If the problem also occurs when using plain <mapframe>...</mapframe> tags, then it should be reported on Phabricator (you can log in with you Wikipedia account). See mw:How to report a bug for instructions (for the tags, use Maps). (Alternatively, you can try mw:Help talk:Extension:Kartographer)
• If the problem only occurs with Wikipedia's template/module, or you're not sure, report it here. (Alternatively, you can try Wikipedia:Village pump (technical))

Q3: Why does the thumbnail map render as a static image when viewing pages, but is interactive when editing pages?

A3: On Wikipedia, and most wikis other than Wikivoyage, the emdeded thumbnail is a static map, and the full screen map needs to be opened before the map can be zoomed or panned. This is for for performance reasons, and to present some content if javascript is disabled, and for printing.
That preview mode shows an interactive map is a bug, phab:T203863 (and also a performance issue). Further explanation can be found in the comments on phab:T202793.

Q4: Why is a line or shape feature from OpenStreetMap not being shown?

A4: There are several possible causes:

• The feature on OSM needs to be tagged with the Wikidata id, per mw:Help:Extension:Kartographer/OSM. It is not enough to just set (P402) on the Wikidata item.
• Only certain OSM relations (those with type=multipolygon, type=route, type=waterway and type=boundary) can be used, and not others like buildings and public transport master routes. See mw:Help:Extension:Kartographer/OSM#Limitation and phab:T156433.
• It can take 1 or 2 days after tagging on OSM before the data is available here.
• Wikimedia occasionally has problems replicating OSM data (e.g. phab:T218097), or intentionally disables replication due to other problems (e.g. phab:T243609)

Q5: Why are line, shape, or point features are not shown after editing or adding a map, even though they were shown in the page preview?

A5: This is a bug related to generating thumbnail map images. It should fix itself in an hour or two. See phab:T269984 for details.

Q6: A page using mapframe's <syntaxhighlight lang="wikitext" inline style="display: none;" />|raw= parameter is showing error messages of "The time allocated for running scripts has expired." What can be done?

A6: If the amount of raw data to be processed is too large, that timeout message may be shown. You can try moving the raw data to Commons (example) or replacing the mapframe template with the equivalent wikitext using Special:ExpandTemplates (example)

Redirects

• {{Map link}}
• {{Mapframe}}

See also

• Wikipedia:Maps for Wikipedia, a list of mapping tools available on Wikipedia
• Wikipedia:Maplink, an informational page about this and similar templates
• Template:Mapbox – a derivative of this template that puts the link inside a right-aligned box
• Template:OSM Location map
• Template:Attached KML
• Template:Rapid transit OSM map