View source for Extension:Kartographer


The '''Kartographer''' extension lets you display maps (based around [[wikipedia:OpenStreetMap|OpenStreetMap]]) in wiki pages. It was specifically designed in order to run on Wikimedia sites such as Wikivoyage and Wikipedia, although it can be used on any wiki.

'''Note:''' the tile server used by default by the Wikimedia Foundation is not available to 3rd parties. Please use your own tileserver.

== Usage ==
Kartographer defines the wikitext tags <code>&lt;mapframe></code> and <code>&lt;maplink></code>, which both display a map on the page. See [[Help:Extension:Kartographer]] for how to call these tags.

== Example ==
<mapframe text="Map of [[wikipedia:London|London]]" latitude="51.505" longitude="-0.126" zoom="8" width="300" height="300" align="left">
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
          "title": "[[wikipedia:London|London]] is the capital of [[wikipedia:United Kingdom|United Kingdom]]",
          "description": "[[File:Houses_of_Parliament.jpg|Houses of Parliament|280px]]",
          "marker-symbol": "town-hall",
          "marker-size": "large",
          "marker-color": "f00"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -0.1226806780323386,
          51.515268213580114
        ]
      }
    }
  ]
}</mapframe>
<br style="clear: both;" clear="all" />

== Installation ==
{{ExtensionInstall
 |composer=yes
 |custom-steps0=* Install the [[Extension:JsonConfig|"JsonConfig" extension]] as described in its documentation which is required to run this extension.
 |custom-steps=* [[#Configuration|Configure as required.]]
 |registration=yes
}}

== Configuration ==
{| class="wikitable"
|+
Configuration settings
!parameter
!default
!comment
|-
| $wgKartographerWikivoyageMode
|<syntaxhighlight lang="php">false</syntaxhighlight>
| Enables Wikivoyage mode.
|-
| $wgKartographerUseMarkerStyle
|<syntaxhighlight lang="php">false</syntaxhighlight>
| href="wikipedia:OpenStreetMap" |Allows Kartographer to extract CSS style to be used by the link from the GeoJSON.
|-
| href="Maps#Production maps cluster" |$wgKartographerStaticMapframe
|<syntaxhighlight lang="php">false</syntaxhighlight>
|Defines if the map will be a static image.
|-
| $wgKartographerEnableMapFrame
|<syntaxhighlight lang="php">true</syntaxhighlight>
| Enables the <nowiki><mapframe></nowiki> tag to be used to create static or interactive maps.
|-
| $wgKartographerMapServer
|<syntaxhighlight lang="php">"https://maps.wikimedia.org"</syntaxhighlight>
| Server providing the map tiles
|-
| $wgKartographerStyles
|<syntaxhighlight lang="json">["osm-intl", "osm"]</syntaxhighlight>
| Available map styles on $wgKartographerMapServer
|}

== Implementation ==
* [[Help:Extension:Kartographer/Developer_guide|Kartographer developer guide]]
* [https://doc.wikimedia.org/Kartographer/master/js/ API documentation]
Kartographer makes use of a suite of open-source, open-data tools for displaying maps:
* On the client side (within the browser):
** [[wikipedia:Leaflet (software)|Leaflet]], a JavaScript mapping library
* On the server side:
** [https://github.com/kartotherian/kartotherian#readme Kartotherian], a map tile service developed by the Wikimedia Foundation, which itself contains code from [[wikipedia:Mapbox|Mapbox]]. Third party installations should use non-Wikimedia tile servers listed on https://wiki.openstreetmap.org/wiki/Tile_servers
* Generating the data in advance:
** [https://github.com/kartotherian/tilerator/blob/master/README.md Tilerator], a tile pre-generation service also developed by the Wikimedia Foundation
** [[wikipedia:OpenStreetMap|OpenStreetMap]], an open map data source, the source for the map data as well as for most of the points of interest (POIs).

For more information on these, see [[Maps#Production maps cluster]]. For more information on the production aspects of running these services, see the Wikitech [https://wikitech.wikimedia.org/wiki/Maps Maps] page.

== Goals ==

=== General goals ===
* A simple method to insert a map into an article without requiring common.js code changes
* Ability to add extra information (marks, area, popups, text, links) to the map
* Ability to gather map usage statistics (KPI) to better gauge how and what should be improved.
* '''TBD:''' experimentation - if the user is aware of the privacy implications, the map should be able to show external data from non-production source, e.g. wmflabs. Static, server-side rendered images will not include the extra data added via this method until the extra data source is hosted in the secure production environment and can be shown without the user action.

=== Wikivoyage goals ===
Wikivoyage tends to have a large number of points of interest (POIs), such as museums and restaurants, listed on a page (see [[voy:Salzburg#Get_around|example]] and scroll down to the "See" section). Each POI is usually added with a template, but all of them should appear on the same map. Also, each POI should be referable by showing an icon with a number, both in the text of the article, and on the map:
* Ability to incrementally add features to the map. For example, each usage of the ''restaurant'' template adds a single POI, and the map shows all of them.
* Added features need to be indexable. E.g. the first ''restaurant'' template would show <sup>[1]</sup> on the page, and map would show POI as a clickable <sup>[1]</sup> element. There could be multiple index counters at the same time, each for its own type of POIs.

== Known problems ==

See the corresponding project(s) in [[Phabricator]] for a [https://phabricator.wikimedia.org/project/board/1127/ complete list of bugs].

<languages />
{{PD Help Page}}
<translate>
<!--T:1-->
The [[<tvar|kartographer>Special:MyLanguage/Extension:Kartographer</>|Kartographer]] extension powers interactive maps on Wikimedia wikis. This page shows techniques for creating  dynamic maps by using the Kartographer tags <tvar|mapframe>{{tag|mapframe|open}}</>, which embeds maps right in wiki pages, and <tvar|maplink>{{tag|maplink|open}}</>, which creates links to dynamic maps. 

== Getting started == <!--T:2-->
</translate>
<mapframe text="Downtown [[wikipedia:San Francisco|San Francisco]]" width=250 height=250 zoom=13 latitude=37.8013 longitude=-122.3988 />
<translate>
<!--T:3-->
This code will insert a simple interactive map, like the one you see in this section with the subject "''Downtown San Francisco''"

<!--T:85-->
*On [[voy:|Wikivoyage]] and [[test2wiki:|test2wiki]], this embedded map is '''interactive'''.</translate> <translate><!--T:86--> A single-click is used to pan the map; double-clicking (or clicking the icon in the right corner) opens a full-screen map, which is also interactive.</translate>
<translate>
<!--T:87-->
*On [[w:|Wikipedia]] and other Wikimedia wikis, this embedded maps is '''static'''.</translate> <translate><!--T:88--> Single-clicking opens a full-screen map, which is interactive.</translate>

<syntaxhighlight lang="xml">
<mapframe text="Downtown [[wikipedia:San Francisco|San Francisco]]" width=250 height=250 zoom=13 latitude=37.8013 longitude=-122.3988 />
</syntaxhighlight>

<translate>
<!--T:4-->
The <tvar|align><code dir="ltr">align</code></> parameter overrides the default alignment to left, right, or center.</translate>
<translate>
<!--T:37-->
The attribute <tvar|zooms><code dir="ltr">zoom</code></> allows for zoom levels between 0 and 19. Zero is the furthest out, 19 the furthest in.

<!--T:99-->
Maps can also be added with the VisualEditor, see section below.

<!--T:104-->
If the map uses features, as explained below, zoom, latitude, and longitude do not need to be set, the map will automatically adjust to fit all features. Width and height however, must always be set.
</translate>

<br clear=all />
<translate>
== <tvar|mapframe><nowiki><mapframe></nowiki></> usage == <!--T:5-->
</translate>
<mapframe text="San Francisco museums" width="350" height="350" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977">
{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [-122.3988, 37.8013] },
  "properties": {
    "title": "[[wikipedia:Exploratorium|Exploratorium]]",
    "description": "[[File:Giant_Mirror_at_the_Exploratorium.jpeg|200px]]",
    "marker-symbol": "museum",
    "marker-size": "large",
    "marker-color": "0050d0"
  }
}
</mapframe>

<translate>
<!--T:6-->
The content of the <tvar|mapframe>{{tag|mapframe|open}}</> tag has to be either empty or a valid GeoJSON with styling, as produced by a [<tvar|geojson>http://geoman.io/</> GeoJSON editor]. Kartographer supports the [<tvar|simple>https://github.com/mapbox/simplestyle-spec/tree/master/1.1.0</> simplestyle specification] with [[<tvar|maki>Special:MyLanguage/Help:Extension:Kartographer/Icons</>|Maki icons]] (Licensed under Creative Commons Zero). [[Help:Extension:Kartographer/Icons]] contains a full list of supported icons.
</translate>

<syntaxhighlight lang="xml">
<mapframe text="San Francisco museums" width=350 height=350 zoom=13 latitude=37.8013 longitude=-122.3988>
{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [-122.3988, 37.8013] },
  "properties": {
    "title": "[[wikipedia:Exploratorium|Exploratorium]]",
    "description": "[[File:Giant_Mirror_at_the_Exploratorium.jpeg|200px]]",
    "marker-symbol": "museum",
    "marker-size": "large",
    "marker-color": "0050d0"
  }
}
</mapframe>
</syntaxhighlight>

<translate>
=== Frames === <!--T:89-->

<!--T:90-->
Frameless maps are good for insertion as part of a template, whereas framed maps are good for insertion directly into the page, either by hand or by using the visual editor.

<!--T:91-->
* To insert a map without a frame, add the "frameless" attribute:</translate> <code dir="ltr">&lt;mapframe frameless ...></code>
<translate>
<!--T:92-->
* To add a caption, use the <tvar|text><code dir="ltr">text="..."</code></> attribute.
</translate>

{{Note|1=<translate><!--T:93--> Adding the text attribute automatically enables a frame, even if there is a <tvar|frameless><code>frameless</code></> attribute.</translate>}}
<br clear=all />

== <nowiki><maplink></nowiki> ==
<translate>
<!--T:7-->
Changing <tvar|mapframe>{{tag|mapframe|open}}</> to <tvar|maplink>{{tag|maplink|open}}</> creates a link to a full screen map:
</translate>

<maplink zoom="13" latitude="37.8103" longitude="-122.3995" />
<syntaxhighlight lang="xml">
<maplink zoom="13" latitude="37.8103" longitude="-122.3995" />
</syntaxhighlight>

<translate>
<!--T:8-->
<tvar|maplink>{{tag|maplink|open}}</> also accepts an extra parameter "text" to specify link text instead of the coordinates:
</translate>

<maplink text="click me" zoom="13" latitude="37.8103" longitude="-122.3995" />
<syntaxhighlight lang="xml">
<maplink text="click me" zoom="13" latitude="37.8103" longitude="-122.3995" />
</syntaxhighlight>

<translate>
<!--T:94-->
Add additional classes to <tvar|1>{{tag|maplink|open}}</> with the class attribute.</translate>
<translate>
<!--T:95-->
For instance <tvar|1><code>no-icon</code></> to hide the pin in front of the link.
</translate>

<maplink class="no-icon" text="click me" zoom="13" latitude="37.8103" longitude="-122.3995" />
<syntaxhighlight lang="xml">
<maplink class="no-icon" text="click me" zoom="13" latitude="37.8103" longitude="-122.3995" />
</syntaxhighlight>

<translate>
<!--T:9-->
The <tvar|maplink>{{tag|maplink|open}}</> tag may contain the same geojson as <tvar|mapframe>{{tag|mapframe|open}}</>.

=== <tvar|maplink><nowiki><maplink></nowiki></> and auto-counters === <!--T:10-->
</translate>
<mapframe text="Several groups of automatic counters" width="350" height="350" zoom="13" latitude="37.80151060070086" longitude="-122.39902496337889">
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.41816520690917,
          37.79097260220947
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.40786552429199,
          37.799654055191525
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.40185737609865,
          37.796262984039544
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.38743782043457,
          37.80535070427755
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.38005638122557,
          37.795449103799726
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-letter",
        "marker-color": "208020"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.40941047668457,
          37.81850557172186
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-letter",
        "marker-color": "208020"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.40357398986815,
          37.81280993744834
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-letter",
        "marker-color": "208020"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.39842414855956,
          37.8071138637568
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number-bar",
        "marker-color": "f01080"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.41181373596191,
          37.78595317184089
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number-bar",
        "marker-color": "f01080"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.39542007446289,
          37.787674400057654
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number-bar",
        "marker-color": "f01080"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.38649368286131,
          37.78401144262929
        ]
      }
    }
  ]
}
</mapframe>

<translate>
<!--T:11-->
<tvar|maplink>{{tag|maplink|open}}</> creates a link that shows a full screen map when clicked. The link text can be set with the <tvar|text><code dir="ltr">text</code></> attribute. Without this attribute, the coordinates will be shown (example: <maplink zoom=5 latitude=12.3 longitude=45.6/>). If a map uses GeoJSON, the <tvar|markersymbol><code dir="ltr">marker-symbol</code></> is set to the magic <tvar|minusnumber><code dir="ltr">'''‑number'''</code></> or <tvar|minusletter><code dir="ltr">'''‑letter'''</code></> value. In this case each <tvar|minusnumber2><code dir="ltr">‑number</code></> will be replaced with an incremental counter <tvar|onetwothree><code dir="ltr">1, 2, 3...</code></>, and <tvar|minusletter2><code dir="ltr">‑letter</code></> with <tvar|az><code dir="ltr">A...Z</code></> values.

<!--T:12-->
If GeoJSON has more than one counter, the value of the first one will be shown as the link text. Optionally, editors may add a suffix to have multiple counters on the page at the same time. This way <tvar|numbermuseum><code dir="ltr">‑number‑museum</code></> will have different counter from <tvar|numberbar><code dir="ltr">‑number‑bar</code></>.

<!--T:13-->
It would make sense to use a distinct color for each counting group. All data added via <tvar|maplink>{{tag|maplink|open}}</> will also be shown in all maps inserted with <tvar|mapframe>{{tag|mapframe|open}}</>, unless the <tvar|group><code dir="ltr">group</code></> attribute is used.
</translate>

<syntaxhighlight lang="xml">
{{see
| name=Exploratorium | url=http://www.exploratorium.edu/
| lat=37.8013 | long=-122.3988
| content=A great museum
}}
</syntaxhighlight>

<translate>
<!--T:14-->
could be expanded into
</translate>

<syntaxhighlight lang="xml">
<maplink zoom=13 latitude=37.8013 longitude=-122.3988>
{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [-122.3988, 37.8013] },
  "properties": {
    "title": "Exploratorium",
    "marker-color": "228b22",
    "marker-symbol": "-number-see"
  }
}
</maplink>
</syntaxhighlight>

<translate>
<!--T:15-->
The attributes <tvar|zoom><code dir="ltr">zoom</code></>, <tvar|latitude><code dir="ltr">latitude</code></>, and <tvar|longitude><code dir="ltr">longitude</code></> control the location of the popup map. Use <tvar|text><code dir="ltr">text</code></> for the text of the link (could be any valid wikitext markup). Use <tvar|group><code dir="ltr">group</code></> to add the contents of this tag to the named group (see below).

== Markers == <!--T:38-->
[[File:Complex map - marker, article link and image.jpg|thumb|Complex map - marker, article link and image]]
Markers can be added to maps to denote a location. These features are added using [[w:Special:MyLanguage/JSON|the JSON format]].</translate>
<translate>
<!--T:96-->
<tvar|1>{{ll|Help:Extension:Kartographer/Icons}}</> contains a full list of icons that can be used as marker symbols.
</translate>

{{note|1=<translate><!--T:39--> These examples use <code>maplink</code>. The formatting for <code>mapframe</code> is the same.</translate>}}

<syntaxhighlight lang="xml">
<maplink text="Colorado State Capital with marker icon" latitude="39.73939" longitude="-104.98491" zoom="17">{"type": "Feature", "properties": { "marker-symbol": "", "marker-color": "46ea5f", "marker-size": "medium"}, "geometry": { "type": "Point", "coordinates": [-104.98485267162323, 39.73928364167763] }}</maplink>
</syntaxhighlight>

<translate><!--T:40--> '''Result:'''</translate> <maplink text="Colorado State Capital with marker icon" latitude="39.73939" longitude="-104.98491" zoom="17">{"type": "Feature", "properties": { "marker-symbol": "", "marker-color": "46ea5f", "marker-size": "medium"}, "geometry": { "type": "Point", "coordinates": [-104.98485267162323, 39.73928364167763] }}</maplink>

<translate>
<!--T:41-->
Markers can also contain information such as images and links to articles.
</translate>

<syntaxhighlight lang="xml">
<maplink text="Colorado State Capital with a town hall marker, article link and image" latitude="39.73939" longitude="-104.98491" zoom="17">
{
      "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] }
}
</maplink>
</syntaxhighlight>

<translate><!--T:42--> '''Result''' (interact with marker to see result):</translate> <maplink text="Colorado State Capital with a town hall marker, article link and image" latitude="39.73939" longitude="-104.98491" zoom="17"> { "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] }}</maplink>

<translate>
<!--T:43-->
Wikidata IDs for OSM data can be used to highlight borders using the geoshape service.
</translate>

<syntaxhighlight lang="xml">
<maplink text="State of Colorado, outlined" zoom=7 > { "type": "ExternalData", "service": "geoshape", "ids": "Q1261" } </maplink>
</syntaxhighlight>

<translate><!--T:44--> '''Result:'''</translate> <maplink text="State of Colorado, outlined" zoom=7 > { "type": "ExternalData", "service": "geoshape", "ids": "Q1261" } </maplink>

<translate>
<!--T:45-->
Wikidata IDs can be used to mask the entire map except a specified region.
</translate>

<syntaxhighlight lang="xml">
<maplink text="State of Colorado, highlighted" zoom=7> { "type": "ExternalData", "service": "geoshape", "ids": "Q1261", "service": "geomask" } </maplink>
</syntaxhighlight>

<translate><!--T:46--> '''Result:'''</translate> <maplink text="State of Colorado, highlighted" zoom=7> { "type": "ExternalData", "service": "geoshape", "ids": "Q1261", "service": "geomask" } </maplink>

<translate>
<!--T:47-->
Markers can be numbered.
</translate>

<syntaxhighlight lang="xml">
<maplink text="Colorado State Capital with a number marker" latitude="39.73939" longitude="-104.98491" zoom="17">{ "type": "Feature", "properties": {  "marker-color": "228b22", "marker-symbol": "-number"}, "geometry": { "type": "Point", "coordinates": [-104.98485267162323, 39.73928364167763] }}</maplink>
</syntaxhighlight>

<translate><!--T:48--> '''Result:'''</translate> <maplink text="Colorado State Capital with a number marker" latitude="39.73939" longitude="-104.98491" zoom="17">{ "type": "Feature", "properties": {  "marker-color": "228b22", "marker-symbol": "-number"}, "geometry": { "type": "Point", "coordinates": [-104.98485267162323, 39.73928364167763] }}</maplink>

<translate>
<!--T:49-->
Markers can use letters.
</translate>

<syntaxhighlight lang="xml"><maplink text="Colorado State Capital with a letter marker" latitude="39.73939" longitude="-104.98491" zoom="17">{ "type": "Feature", "properties": {  "marker-color": "508e33", "marker-symbol": "-letter"}, "geometry": { "type": "Point", "coordinates": [-104.98485267162323, 39.73928364167763] }}</maplink>
</syntaxhighlight>

<translate><!--T:50--> '''Result:'''</translate> <maplink text="Colorado State Capital with a letter marker" latitude="39.73939" longitude="-104.98491" zoom="17">{ "type": "Feature", "properties": {  "marker-color": "508e33", "marker-symbol": "-letter"}, "geometry": { "type": "Point", "coordinates": [-104.98485267162323, 39.73928364167763] }}</maplink>

<translate>
<!--T:51-->
Add several map markers in different sizes using a feature collection.
</translate>

<syntaxhighlight lang="xml"><maplink text="Denver Amusements" latitude="39.74956567318853" longitude="-105.01247406005858" zoom="14"> {"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" } },]}</maplink>
</syntaxhighlight>

<translate><!--T:52--> '''Result:'''</translate> <maplink text="Denver Amusements" latitude="39.74956567318853" longitude="-105.01247406005858" zoom="14"> {"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" } },]}</maplink>

<translate>
<!--T:53-->
Add groups of different colored map markers and different counters.
</translate>

<syntaxhighlight lang="xml"><maplink text="Add groups of different colored markers and different counters" width="350" height="350" zoom="13" longitude="-122.39902496337889" latitude="37.80151060070086"> {
"type": "FeatureCollection", "features":  [
    { "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060" },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.41816520690917, 37.79097260220947 ] }},
    { "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.40786552429199, 37.799654055191525 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.40185737609865, 37.796262984039544 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.38743782043457, 37.80535070427755 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.38005638122557, 37.795449103799726 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-letter",
        "marker-color": "208020"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.40941047668457, 37.81850557172186 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-letter",
        "marker-color": "208020"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.40357398986815, 37.81280993744834 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-letter",
        "marker-color": "208020"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.39842414855956, 37.8071138637568 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number-bar",
        "marker-color": "f01080"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.41181373596191, 37.78595317184089 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number-bar",
        "marker-color": "f01080"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.39542007446289, 37.787674400057654 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number-bar",
        "marker-color": "f01080"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.38649368286131, 37.78401144262929 ] }}
  ] }</maplink>
</syntaxhighlight>

<translate><!--T:54--> '''Result:'''</translate> <maplink text="Add groups of different colored markers and different counters" width="350" height="350" zoom="13" longitude="-122.39902496337889" latitude="37.80151060070086"> {
"type": "FeatureCollection", "features":  [
    { "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060" },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.41816520690917, 37.79097260220947 ] }},
    { "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.40786552429199, 37.799654055191525 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.40185737609865, 37.796262984039544 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.38743782043457, 37.80535070427755 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number",
        "marker-color": "302060"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.38005638122557, 37.795449103799726 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-letter",
        "marker-color": "208020"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.40941047668457, 37.81850557172186 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-letter",
        "marker-color": "208020"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.40357398986815, 37.81280993744834 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-letter",
        "marker-color": "208020"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.39842414855956, 37.8071138637568 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number-bar",
        "marker-color": "f01080"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.41181373596191, 37.78595317184089 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number-bar",
        "marker-color": "f01080"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.39542007446289, 37.787674400057654 ] }},
    {
      "type": "Feature",
      "properties": {
        "marker-symbol": "-number-bar",
        "marker-color": "f01080"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [ -122.38649368286131, 37.78401144262929 ] }}
  ] }</maplink>

<translate>
<!--T:55-->
* Map markers can use any color that has a [[:en:Color_tool|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.
* GeoJSON that is created elsewhere can be copied (in accordance with licensing and copyright restrictions) and then pasted into <tt>maplink</tt> ([http://geojson.io/ for example])
* If you are creating maps on Wikivoyage, it might be a good idea to use Groups (see below).
* If you want to learn more about adding external data to your map, [[:mw:Help:Extension:Kartographer#External_data|see the External data section]].

== Groups == <!--T:16-->
</translate>
{{Note|1=<translate><!--T:22--> '''The groups feature is only available in Wikivoyage''' (per VisualEditor team request)</translate>}}

<translate>
<!--T:17-->
For use on the Wikivoyage project, there is a need to show a map whose data is defined somewhere else on the page. For example, there may be multiple points of interest (POI) defined with <tvar|maplink>{{tag|maplink|open}}</> tags, and one common map on the side of the page that shows them all.

<!--T:20-->
The grouping concept allows editors to share data between multiple <tvar|mapframe>{{tag|mapframe|open}}</> and <tvar|maplink>{{tag|maplink|open}}</> tags.

<!--T:18-->
By default, the data inside the <tvar|mapframe>{{tag|mapframe|open}}</> or <tvar|maplink>{{tag|maplink|open}}</> tag is shown only for that one tag, and will not be shown anywhere else.

<!--T:21-->
If <tvar|mapframe>{{tag|mapframe|open}}</> or <tvar|maplink>{{tag|maplink|open}}</> specify the <tvar|group><code dir="ltr">group="..."</code></> attribute, the data inside those tags will be placed into a named group, together with all the other data by the same group name. As a result, any tags with the same group name will show the same map data, and each tag may incrementally add data to the group.

<!--T:19-->
A tag may also show other groups, regardless if it belongs to a group or not, by specifying the <tvar|show><code dir="ltr">show="..."</code></> attribute. Comma-separated multiple group names may be specified. The group name may only contain lower case English letters. This matrix shows what data will be shown for each tag.
</translate>

<syntaxhighlight lang="xml" line="1">
<maplink>                               -- shows 1
<maplink group='food'>                  -- shows   2   4       8   10
<maplink group='bar'  show='bar'>       -- shows     3           9
<maplink group='food' show='bar'>       -- shows   2 3 4       8 9 10
<maplink              show='bar'>       -- shows     3   5       9
<maplink              show='food,bar'>  -- shows   2 3 4   6   8 9 10
<mapframe>                              -- shows             7
<mapframe group='food'>                 -- shows   2   4       8   10
<mapframe group='bar'  show='bar'>      -- shows     3           9
<mapframe group='food' show='bar'>      -- shows   2 3 4       8 9 10
<mapframe              show='bar'>      -- shows     3           9    11
<mapframe              show='food,bar'> -- shows   2 3 4       8 9 10    12
</syntaxhighlight>

== <translate><!--T:23--> External data</translate> ==

<mapframe text="A geoshape of Alaska" width=300 height=300 zoom=3 latitude=64.01 longitude=-152.58>
{
  "type": "ExternalData",
  "service": "geoshape",
  "ids": "Q797"
}
</mapframe>

<translate>
<!--T:24-->
In addition to drawing polygons using GeoJSON, you may also get outlines of the well known geographical objects by their Wikidata ID if they are marked as such in the OpenStreetMap database. For example, the Wikidata item for Alaska is [[wikidata:Q797|Q797]], and we can draw it on a map by using the "external data" reference. More than one ID may be specified separated by a comma.</translate>
<translate>
<!--T:27-->
To create a mask over the areas of interest, use the "geoshape" service. To invert this and create a mask over everything else, use the "geomask" service.
</translate>

{{note|1=<translate><!--T:25--> Wikidata IDs are relatively new to the OSM community. There are about [<tvar|url>https://taginfo.openstreetmap.org/keys/?key=wikidata</> 1.3 million features] with IDs. To add more, visit https://www.openstreetmap.org/ and add <tvar|wikidata><code>wikidata</code></> tag with the <tvar|q><code>Q</code></> value (see [<tvar|osm>https://wiki.openstreetmap.org/wiki/Key:wikidata</> Key:wikidata on OSM wiki] for an easier way to do it).</translate> <translate><!--T:28--> For detailed instructions, see <tvar|help>{{ll|Help:Extension:Kartographer/OSM}}</>.</translate> <translate><!--T:97--> The data normally becomes available to Kartographer within 2 days.</translate> <translate><!--T:98--> However, as of April 2020, [[<tvar|1>phab:T218097#6011573</>|no tags added since late January 2020]] are recognized by Kartographer due to [[<tvar|2>phab:T243609</>|a pause in updates]].</translate>}}

<syntaxhighlight lang="xml">
<mapframe text="A geoshape of Alaska" width=300 height=300 zoom=3 latitude=64.01 longitude=-152.58>
{
  "type": "ExternalData",
  "service": "geoshape",
  "ids": "Q797"
}
</mapframe>
</syntaxhighlight>
<br clear=all />

=== <translate><!--T:56--> GeoShapes via Wikidata Query</translate> ===

<mapframe latitude="52" longitude="-110" zoom="3" width="500" height="500" text="Governors of US states with their party affiliation">
{
  "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('[[wikipedia:', substr(str(?link),31,500),  '{{!}}', ?headLabel, ']]') as ?title) (concat(?stateLabel, '\\n', '[[File:', substr(str(?img_), 52, 500), '{{!}}200px]]') 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>

<translate>
<!--T:26-->
While this helps with the simple use cases when the Wikidata ID is well known, sometimes you may want to get a list of IDs as a result of a Wikidata query. A SPARQL query gets a list of all US states in the ID column of the result, and geoshapes service adds the geometrical outlines for each state. All other columns in the SPARQL query result become values in the "properties" object. The "fill" column changes the color of the state. The "title" column shows state governor's name, and "description" has wiki markup to show the state name and the governor's picture.  To edit this query, copy the query parameter after the "#" symbol at '''<nowiki>https://query.wikidata.org/#...</nowiki>''':
</translate>

<syntaxhighlight lang="xml">
<mapframe latitude="52" longitude="-110" zoom="3" width="500" height="500" text="Governors of US states with their party affiliation">
{
  "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('[[wikipedia:', substr(str(?link),31,500),  '{{!}}', ?headLabel, ']]') as ?title) (concat(?stateLabel, '\\n', '[[File:', substr(str(?img_), 52, 500), '{{!}}200px]]') 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>

<translate>
===Map data from Commons=== <!--T:29-->
</translate>

:''<translate><!--T:30--> Further information:</translate> {{ll|Help:Map Data}}''

{{caution|The map loader does not currently support chained ExternalData calls. If a resource of type ExternalData is fetched that itself relies on ExternalData references, loading will fail.  See {{phab|T155927}} and {{phab|T193458}}. }}

<translate>
<!--T:36-->
Map data stored on Commons can be drawn on the map. For example, [[c:Data:Neighbourhoods/New York City.map]]:
</translate>

<mapframe width=300 height=400 zoom=11 latitude=40.7920 longitude=-73.9751>
{
  "type": "ExternalData",
  "service": "page",
  "title": "Neighbourhoods/New York City.map"
}
</mapframe>

<syntaxhighlight lang="json">
<mapframe width=300 height=400 zoom=11 latitude=40.7920 longitude=-73.9751>
{
  "type": "ExternalData",
  "service": "page",
  "title": "Neighbourhoods/New York City.map"
}
</mapframe>

</syntaxhighlight>

<br clear=all />

=== <translate><!--T:57--> Combining multiple data types</translate> ===
<mapframe text="Caderousse city wall" width="300" height="300" zoom="15" latitude="44.10200" longitude="4.75600" >
[
  {
    "type": "ExternalData",
    "service": "geoshape",
    "ids": "Q13518258",
    "properties": {
      "stroke": "#ffb100",
      "stroke-width": 6,
    }
  },
  {
    "type": "Feature",
    "geometry": { "type": "Point", "coordinates": [4.75566, 44.104498] },
    "properties": {
      "title": "Porte de Castellan"
    }
  },
  {
    "type": "Feature",
    "geometry": { "type": "Point", "coordinates": [4.75829, 44.10258] },
    "properties": {
      "title": "Porte Léon Roche"
    }
  }
]
</mapframe>

<translate>
<!--T:58-->
You can combine ExternalData, Feature, and FeatureCollection together in the same &lt;mapframe> or &lt;maplink> element:
</translate>

<syntaxhighlight lang="xml">
<mapframe text="Caderousse city wall" width="300" height="300" zoom="15" latitude="44.10200" longitude="4.75600">
[
  {
    "type": "ExternalData",
    "service": "geoshape",
    "ids": "Q13518258",
    "properties": {
      "stroke": "#ffb100",
      "stroke-width": 6,
    }
  },
  {
    "type": "Feature",
    "geometry": { "type": "Point", "coordinates": [4.75566, 44.104498] },
    "properties": {
      "title": "Porte de Castellan"
    }
  },
  {
    "type": "Feature",
    "geometry": { "type": "Point", "coordinates": [4.75829, 44.10258] },
    "properties": {
      "title": "Porte Léon Roche"
    }
  }
]
</mapframe>
</syntaxhighlight>

<mapframe width="300" height="300" zoom="12" latitude="40.782222" longitude="-73.965278">
 [
  {
    "type": "ExternalData",
    "service": "page",
    "title": "Neighbourhoods/New York City.map"
  },
  {
    "type": "ExternalData",
    "service": "geoshape",
    "ids": "Q160409",
    "properties": {
      "fill": "#07c63e", "title": "Central Park"
    }
  },
  {
    "type": "Feature",
    "properties": {"title": "Roosevelt Island", "marker-color": "f01080"},
    "geometry": {
      "type": "Point",
      "coordinates": [
        -73.94511222839355,
        40.76734665426719
      ]
    }
  }
]
</mapframe>

<translate>
<!--T:59-->
Map data from Commons can be combined with other types of data:
</translate>

<syntaxhighlight lang="json">
<mapframe width="300" height="300" zoom="12" latitude="40.782222" longitude="-73.965278">
[
  {
    "type": "ExternalData",
    "service": "page",
    "title": "Neighbourhoods/New York City.map"
  },
  {
    "type": "ExternalData",
    "service": "geoshape",
    "ids": "Q160409",
    "properties": {
      "fill": "#07c63e", "title": "Central Park"
    }
  },
  {
    "type": "Feature",
    "properties": {"title": "Roosevelt Island", "marker-color": "f01080"},
    "geometry": {
      "type": "Point",
      "coordinates": [
        -73.94511222839355,
        40.76734665426719
      ]
    }
  }
]
</mapframe>
</syntaxhighlight>
<br clear=all />

== <translate><!--T:60--> Styling</translate> ==
=== <translate><!--T:61--> Styling Wikidata ID elements</translate> ===
<mapframe text="Interstate Highway I-696" width="300" height="300" latitude="42.4883" longitude="-83.2297" zoom="9">
{
  "type": "ExternalData",
  "service": "geoline",
  "ids": "Q2108",
  "properties": {
    "title": "Highway I-696",
    "description": "[[File:I696-1988.JPG|200px]]",
    "stroke": "#ffb100",
    "stroke-width": 8
  }
}
</mapframe>

<translate>
<!--T:62-->
For external data, you can also add styles and titles, using the '''properties''' keyword:
</translate>

<syntaxhighlight lang="json">
<mapframe text="Interstate Highway I-696" width="300" height="300" latitude="42.4883" longitude="-83.2297" zoom="9">
{
  "type": "ExternalData",
  "service": "geoline",
  "ids": "Q2108",
  "properties": {
    "title": "Highway I-696",
    "description": "[[File:I696-1988.JPG|200px]]",
    "stroke": "#ffb100",
    "stroke-width": 8
  }
}
</mapframe>
</syntaxhighlight>

<translate>
<!--T:63-->
The main style keys are: "stroke" (color), "stroke-width", "stroke-opacity", "fill" (color), "fill-opacity".
</translate>

<br clear=all />

=== <translate><!--T:64--> Overlapping elements</translate> ===
<translate>
<!--T:65-->
Map elements that overlap are drawn in the order in which they are written in the code. For instance, if a map includes two lines that overlap, the line that is defined first will appear beneath the line that is defined second. The following examples show how this can affect the appearance of the map:
</translate>

<mapframe width="500" height="270" latitude="-24.794" longitude="79.030" zoom="8" align="center">
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {"fill": "#ff0000","fill-opacity": 0.7,"stroke-width": 0},
"geometry": {
 "type": "Polygon",
 "coordinates": [
 [
 [
 77.926025390625,
 -25.150257104114733
 ],
 [
 80.14251708984374,
 -25.150257104114733
 ],
 [
 80.14251708984374,
 -24.43714786161562
 ],
 [
 77.926025390625,
 -24.43714786161562
 ],
 [
 77.926025390625,
 -25.150257104114733
 ]
 ]
 ]
 }
 },
{
"type": "Feature",
"properties": {"stroke": "#fffa00","stroke-width": 5},
"geometry": {
 "type": "LineString",
 "coordinates": [
 [
 77.926025390625,
 -25.150257104114733
 ],
 [
 80.14251708984374,
 -24.43714786161562
 ]
 ]
 }
 },
{
"type": "Feature",
"properties": {"stroke": "#000000","stroke-width": 5},
"geometry": {
 "type": "LineString",
 "coordinates": [
 [
 77.926025390625,
 -24.43714786161562
 ],
 [
 80.14251708984374,
 -25.150257104114733
 ]
 ]
 }
 }
 ]
}
</mapframe>

<syntaxhighlight lang="json">
<mapframe width="500" height="270" latitude="-24.794" longitude="79.030" zoom="8" align="center">
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {"fill": "#ff0000","fill-opacity": 0.7,"stroke-width": 0},
"geometry": {
 "type": "Polygon",
 "coordinates": [
 [
   [77.926025390625, -25.150257104114733],
   [80.14251708984374, -25.150257104114733],
   [80.14251708984374, -24.43714786161562],
   [77.926025390625, -24.43714786161562],
   [77.926025390625, -25.150257104114733]
 ]
 ]
 }
 },
{
"type": "Feature",
"properties": {"stroke": "#fffa00","stroke-width": 5},
"geometry": {
 "type": "LineString",
 "coordinates": [
   [77.926025390625, -25.150257104114733],
   [80.14251708984374, -24.43714786161562]
 ]
 }
 },
{
"type": "Feature",
"properties": {"stroke": "#000000","stroke-width": 5},
"geometry": {
 "type": "LineString",
 "coordinates": [
   [77.926025390625, -24.43714786161562],
   [80.14251708984374, -25.150257104114733]
 ]
 }
 }
 ]
}
</mapframe>
</syntaxhighlight>

<translate>
<!--T:66-->
The code for the map above includes three elements, all of which use GeoJSON's "feature" functionality. The first feature is a "Polygon" - the red rectangle. This is followed by two "LineString" features. The yellow line is defined first, so it appears beneath the black line. Note that the hierarchy used to draw elements applies regardless of whether the data is raw GeoJSON or comes from a Wikidata ID or Commons data page.

<!--T:67-->
The map below changes the order from that of the first example: the black line is defined first and is thus moved to the bottom of the stack:
</translate>

<mapframe width="500" height="270" latitude="-24.794" longitude="79.030" zoom="8" align="center">
{
  "type": "FeatureCollection",
  "features": [
{
"type": "Feature",
"properties": {"stroke": "#000000","stroke-width": 5},
"geometry": {
 "type": "LineString",
 "coordinates": [
 [
 77.926025390625,
 -24.43714786161562
 ],
 [
 80.14251708984374,
 -25.150257104114733
 ]
 ]
 }
},
{
"type": "Feature",
"properties": {"fill": "#ff0000","fill-opacity": 0.7,"stroke-width": 0},
"geometry": {
 "type": "Polygon",
 "coordinates": [
  [
  [
  77.926025390625,
  -25.150257104114733
  ],
  [
  80.14251708984374,
  -25.150257104114733
  ],
  [
  80.14251708984374,
  -24.43714786161562
  ],
  [
  77.926025390625,
  -24.43714786161562
  ],
  [
  77.926025390625,
  -25.150257104114733
  ]
  ]
  ]
  }
},
{
"type": "Feature",
"properties": {"stroke": "#fffa00","stroke-width": 5},
"geometry": {
 "type": "LineString",
 "coordinates": [
 [
 77.926025390625,
 -25.150257104114733
 ],
 [
 80.14251708984374,
 -24.43714786161562
 ]
 ]
 }
 }
 ]
}
</mapframe>

<translate>
== Rendering options == <!--T:31-->

<!--T:32-->
The following table shows how a <nowiki><mapframe></nowiki> map can be formatted for display on a wiki page. The table contains two columns: the first shows an interactive map via the <nowiki><mapframe></nowiki> tag, and the second showing the rendering of an example image with the same options.
</translate>

{|class="wikitable"
|-
! style="width: 13em" | <translate><!--T:33--> Options</translate>
! <translate><!--T:34--> Rendering a <tvar|mapframe>{{tag|mapframe|open}}</></translate>
! <translate><!--T:35--> Rendering an [[<tvar|helpImages>Special:MyLanguage/Help:Images</>|image]]</translate>
|-
! style="text-align: left" |
* Format: '''frame'''
* Alignment: '''undefined'''
| style="vertical-align: top" | ... text text text <mapframe width="200" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977"></mapframe> text text text ...
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frame|200px]] text text text ...
|-
! style="text-align: left" |
* Format: '''frame'''
* Alignment: '''none'''
| Not supported, see {{phab|T157502}}.
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frame|none|200px]] text text text ...
|-
! style="text-align: left" |
* Format: '''frame'''
* Alignment: '''left'''
| style="vertical-align: top" | ... text text text <mapframe width="200" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977" align="left"></mapframe> text text text ...
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frame|left|200px]] text text text ...
|-
! style="text-align: left" |
* Format: '''frame'''
* Alignment: '''center'''
| style="vertical-align: top" | ... text text text <mapframe width="200" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977" align="center"></mapframe> text text text ...
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frame|center|200px]] text text text ...
|-
! style="text-align: left" |
* Format: '''frame'''
* Alignment: '''right'''
| style="vertical-align: top" | ... text text text <mapframe width="200" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977" align="right"></mapframe> text text text ...
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frame|{{dir|{{pagelang}}|left|right}}|200px]] text text text ...
|-
! style="text-align: left" |
* Format: '''frameless'''
* Alignment: '''undefined'''
| style="vertical-align: top" | ... text text text <mapframe width="200" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977" frameless></mapframe> text text text ...<br clear=all /><br/>'''Inconsistent''', see {{phab|T157640}}.
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frameless|200px]] text text text ...
|-
! style="text-align: left" |
* Format: '''frameless'''
* Alignment: '''none'''
| Not supported, see {{phab|T157502}}.
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frameless|none|200px]] text text text ...
|-
! style="text-align: left" |
* Format: '''frameless'''
* Alignment: '''left'''
| style="vertical-align: top" | ... text text text <mapframe width="200" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977" frameless align="left"></mapframe> text text text ...
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frameless|left|200px]] text text text ...
|-
! style="text-align: left" |
* Format: '''frameless'''
* Alignment: '''center'''
| style="vertical-align: top" | ... text text text <mapframe width="200" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977" frameless align="center"></mapframe> text text text ...
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frameless|center|200px]] text text text ...
|-
! style="text-align: left" |
* Format: '''frameless'''
* Alignment: '''right'''
| style="vertical-align: top" | ... text text text <mapframe width="200" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977" frameless align="right"></mapframe> text text text ...
| style="vertical-align: top" | ... text text text [[File:Example en.svg|frameless|{{dir|{{pagelang}}|left|right}}|200px]] text text text ...
|}

Use the width value <code>full</code> in order to make the map take up the full width of the page.
<syntaxhighlight lang=xml>
<mapframe width="full" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977" align="left"></mapframe>
</syntaxhighlight>
<mapframe width="full" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977"></mapframe>
<mapframe width="full" height="200" zoom="13" latitude="37.81032643553478" longitude="-122.39953994750977" frameless></mapframe>

== <translate><!--T:68--> Map languages</translate> ==
<translate>
<!--T:69-->
Map labels will try to use the language of the wiki where the embedded map is displayed. If that language is not available, then the map will use fallback language as described.

<!--T:80-->
# Look for value in the requested language
# Look for value in a language (or languages) that are specifically defined as fallback languages
# Look for a transliterated value
# Look for label in the local language
# If no value is found, display no label. 

<!--T:70-->
You can specify the language to use for labels by adding the <code>lang=</code> followed by [[m:Language_codes|the desired language code]]. e.g. lang="ja" to display labels in Japanese (if available).
</translate>

<syntaxhighlight lang="xml">
<maplink text="Brussels, Belgium" width="250" height="250" zoom=13 latitude=50.85 longitude=4.35 lang="ja"/>
</syntaxhighlight>

<translate><!--T:71--> Result:</translate> <maplink text="Brussels, Belgium" width="250" height="250" zoom=13 latitude=50.85 longitude=4.35 lang="ja"/>

<translate>
<!--T:72-->
If you wish to use the language local to an area you can use <code>lang=local</code>. This shows map labels in the languages of the area mapped (essentially opting out of internationalization). [[Map_improvements_2018#April_26,_2018:_OSM_name_data_quirks_and_the_uses_of_lang=%E2%80%9Clocal%E2%80%9D|This post gives more guidance]] about when, and why, you might wish to user lang="local"—and generally explains how OpenStreetMap multilingual data works.

<!--T:81-->
Without the <code>lang=</code> attribute, maps will display in the language of the wiki in which they appear.

===Map language fallbacks=== <!--T:82-->

<!--T:83-->
Initially these fallbacks follow [https://translatewiki.net/wiki/Translatewiki.net_languages#Fallback_language_(MediaWiki) those found in MediaWiki]. The language fallbacks for Maps are stored in [https://github.com/kartotherian/babel/blob/master/lib/fallbacks.json fallbacks.json] and can be made different than the MediaWiki settings. Individual Wikimedia projects can [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?title=Request%20to%20change%20Maps%20fallback%20for%20XXXX%20Wiki&tags=Maps&description=Please%20provide%20a%20link%20to%20community%20consensus%20for%20this%20change.%0A%0AA%20description%20of%20the%20requested%20fallback%20is%20also%20needed. request a change to this fallback process] in Phabricator. More Technical information can be found in [https://phabricator.wikimedia.org/T192701 T192701].

<!--T:73-->
Maps use map data, including map label data for all languages, from the open-source mapping project [https://www.openstreetmap.org/ OpenStreetMap]. If the map you want to display doesn’t offer labels in the desired language, you can add labels in that language by adding them to OpenStreetMap. To get you started, there is an [https://wiki.openstreetmap.org/wiki/Beginners%27_guide OpenStreetMap Beginners’ Guide], and [https://wiki.openstreetmap.org/wiki/Names guidance about naming conventions].

==== A community can decide to change its language fallbacks ==== <!--T:100-->

<!--T:101-->
[[<tvar|1>Special:MyLanguage/Map improvements 2018#May 11, 2018: Should your wiki change its map fallback language?</>|Read all about changing your language's fallbacks]] on the Map Improvements project page.

== VisualEditor == <!--T:102-->
</translate>
[[File:Mapframe Kartographer demo.webm|400px|thumb|left|<translate><!--T:103--> Demonstration of how to add a map and a marker in VisualEditor.</translate>]]
<br clear=all />

== <translate><!--T:74--> See also</translate> ==
* [[wmf:Maps Terms of Use|<translate><!--T:84--> Terms of Use for Maps</translate>]]
* [[Help:VisualEditor/Maps]] - How to add and edit maps with the visual editor
* [[Help:Extension:Kartographer/OSM|<translate><!--T:75--> Information on using OSM objects in maps</translate>]]
* [[Maps project (2015-2017)]] - <translate><!--T:76--> Documentation on the Wikimedia engineering activity from the Discovery team from 2015 to 2017</translate>
* [[Map improvements 2018]] - <translate><!--T:77--> Documentation on the Wikimedia engineering activity from the Collaboration team in 2018</translate>
* [[Help:Extension:Kartographer/Developer guide|<translate><!--T:79--> Kartographer Developer guide</translate>]]

[[Category:Extension help{{#translation:}}|Kartographer]]
[[Category:Mapping{{#translation:}}]]