User:Dan Shick (WMDE)/Drafts/Help:Extension:Kartographer

The Kartographer extension powers custom interactive and static maps on Wikimedia wiki pages. This page is an exhaustive reference to using Kartographer, including the many options available when using the tags, which embeds maps directly in wiki pages, and  , which creates links to full-page interactive maps, as well as covering several common elements of GeoJSON often used in maps. You'll find a wealth of examples at the bottom of the page.

Maps and tags
To place a map or a map link directly on a wiki page, Kartographer offers two tags:, which embeds a map inline, and  , which creates a link to a full-screen interactive map.

Some wikis wrap these tags in templates, such as Mapbox and Mapframe. Consult your local wiki for similar templates -- or use the tags themselves.



The tag embeds a map in a wiki page. The tag must be either empty or contain valid GeoJSON with styling, as produced by a GeoJSON editor. See below for a list of GeoJSON resources.

The tag creates a link to a full-screen map.

and. {| class="wikitable" !Parameter !Value !Description Maplink: Defines the text of the link which, when clicked, displays the full-screen map ( query parameter), so that embedded maps can be subjected to the same verification process as other content on a wiki page.
 * width, height
 * pixels, percentage of screen, "full"
 * The width and height of the map frame.
 * zoom
 * 0-19
 * The level of map detail. Zoom level 0 displays the entire available map, and zoom level 19 shows the highest level of detail.
 * latitude, longitude
 * decimal degrees
 * The position on earth. (See this article in the GIS wiki for detailed information.)
 * align
 * "left", "center", "right"
 * The horizontal position of the map frame on the page.
 * lang
 * language code, "local"
 * The language to be used for map labels and markers. "local" uses the language of the area shown in the map. Note: Not all labels are available in every language.
 * text
 * wikitext
 * Mapframe: Caption below the map frame. (Causes the frameless parameter to be ignored if specified.)
 * language code, "local"
 * The language to be used for map labels and markers. "local" uses the language of the area shown in the map. Note: Not all labels are available in every language.
 * text
 * wikitext
 * Mapframe: Caption below the map frame. (Causes the frameless parameter to be ignored if specified.)
 * Mapframe: Caption below the map frame. (Causes the frameless parameter to be ignored if specified.)

GeoJSON
The and  tags can either be empty or contain valid GeoJSON.

A wiki page may also link to raw GeoJSON stored on Wikimedia Commons: see Help:Map_Data  for details.

You will find a helpful introduction to GeoJSON [ https://www.developer.here.com/blog/an-introduction-to-geojson here] and the full specification [ https://datatracker.ietf.org/doc/html/rfc7946 here].

Markers
Maps that use GeoJSON may contain one or more markers to point out special locations. These markers are set using marker-specific keywords under the "properties" level in GeoJSON.

Kartographer supports the [ https://github.com/mapbox/simplestyle-spec/tree/master/1.1.0 simplestyle] specification with Maki icons, which are available under the CC0 license. See Help:Extension:Kartographer/Icons for the full list of supported icons.

Result:

Auto-counters
 { "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        ]      }    }  ] }

You can add a suffix to the value of to create multiple counters on the map. For example, using both and  would create separate counters for your lists of museums and of libraries. If more than one counter is specified, the link text will be set to the first counter's value.

For a rich variety of examples, see the Examples section.

Languages and fallbacks
By default, Kartographer tries to display map labels in the language of the wiki in which the embedded map is displayed. If that language is not available, then the map will use the given wiki's configured fallback language, then any transliterated value available, and finally the local language in the map region specified in the Kartographer map. If none of these are available, Kartographer will display no label.

You can specify the language to use for labels with the  parameter and by setting its value to the desired language code Example:   will display labels in Japanese, if available.

To use the language local to the map area, specify. For more information about using the local language in your labels, and about OpenStreetMap multilingual data in general, read this post. Kartographer maps get their data, including map label data in all available languages, from the open-source mapping project OpenStreetMap. If the map you want to display doesn't offer labels in the desired language, you can always add labels in that language by adding them yourself to OpenStreetMap. To get started, see the OpenStreetMap Beginners’ Guide and these best practices in naming conventions.

External data
 { "type": "ExternalData", "service": "geoshape", "ids": "Q797" }

GeoJSON allows you to obtain outlines of well-known geographical objects from external sources using the "type" parameter with the value "ExternalData".

Maps can draw from well-known geographical objects in the OpenStreetMap database by using their Wikidata ID as well as objects stored in Wikimedia Commons.

Geoshapes via Wikidata ID
Wikidata IDs are relatively new to the OSM community. As of early 2022 there are roughly [ https://taginfo.openstreetmap.org/keys/?key=wikidata 1.9 million features] with Wikidata IDs. You can add your own at https://www.openstreetmap.org/ -- be sure to add the tag and the corresponding  value. The data typically becomes available to Kartographer within two days. Learn more at the OSM wiki.

GeoShapes via Wikidata query
 { "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', '') 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  .} GROUP BY ?id ?head ?headLabel ?link ?stateLabel" } Instead of a Wikidata Item ID, a map can also derive geoshapes from a well-formed Wikidata query in SPARQL.

For detailed instructions, see.

Map data from Commons
 { "type": "ExternalData", "service": "page", "title": "Neighbourhoods/New York City.map" }
 *  Further information: 

Map data in GeoJSON that is stored on Commons can be drawn on the map.

Combining multiple data types
You can combine ExternalData, Feature, and FeatureCollection together in the same  or   element.

Map data from Commons can be combined with other types of data simply by grouping them in parallel blocks of GeoJSON. See for various combinations.

Styling Wikidata ID elements
 { "type": "ExternalData", "service": "geoline", "ids": "Q2108", "properties": { "title": "Highway I-696", "description": "", "stroke": "#ffb100", "stroke-width": 8 } }

When bringing in external data using, you can add styling information and titles, using the properties keyword:

Overlapping elements
Map elements that overlap are drawn in the order they appear in the code. If a map includes two lines that overlap, the line defined first will appear beneath the line defined next. This applies to any elements defined in the code that draw on the map.

Examples
 { "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 ] ] } } ] }

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.

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:

 { "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 ] ] } } ] }

Groups for Wikivoyage
The Wikivoyage project needs to display maps whose data is defined elsewhere on the page. There may be multiple points of interest (POI) defined with tags, all of which appear on a single common map on the side of the page.

Grouping allows editors to share data between multiple and  tags.

Normally, the data inside the or  tag is shown only for that tag and nowhere else.

But if or  specifies the  attribute, the data inside those tags will be placed into a named group alongside all the other data with the same group name. Tags with the same group name will display the same map data; each tag incrementally adds data to the group.

A tag may also show other groups, regardless of whether it belongs to a group, by specifying the attribute. Comma-separated multiple group names may be specified. The group name may only contain lower case Latin letters. This grid illustrates the data that will be shown for each tag.

Example:

Rendering options
The following table shows how a map can be formatted for display on a wiki page. The table contains two columns: the first shows an interactive map via the tag, and the second shows the rendering of an example image with the same options.

Use the width value  in order to make the map take up the full width of the page.  

Simple
 { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-122.3988, 37.8013] }, "properties": { "title": "Exploratorium", "description": "", "marker-symbol": "museum", "marker-size": "large", "marker-color": "0050d0" } }

Groups of automatic counters
 { "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        ]      }    }  ] }

Wikidata query
 { "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', '') 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  .} GROUP BY ?id ?head ?headLabel ?link ?stateLabel" }

Map data from Commons
<mapframe width=300 height=400> { "type": "ExternalData", "service": "page", "title": "Neighbourhoods/New York City.map" }

Mixed types
<mapframe text="Caderousse city wall" width="300" height="300" zoom="15" longitude="4.75600" latitude="44.10200"> [ {    "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" } } ]

Mixed types with markers
<mapframe width="300" height="300" zoom="12" longitude="-73.965278" latitude="40.782222"> [ {    "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      ]    }  } ]

Styling
<mapframe text="Interstate Highway I-696" width="300" height="300" longitude="-83.2297" latitude="42.4883" zoom="9"> { "type": "ExternalData", "service": "geoline", "ids": "Q2108", "properties": { "title": "Highway I-696", "description": "", "stroke": "#ffb100", "stroke-width": 8 } }