Help:Extension:Kartographer

This page documents how to use the kartographer>Special:MyLanguage/Extension:Kartographer|Kartographer extension and its  and  tags.

Getting started


This code will insert a simple interactive map (like what you see on the right), with the ability to maximize it by either double-clicking the map or clicking the icon in the right corner.

You may use the   parameter to override default alignment to left, right, or center.

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

The content of the  tag has to be either empty or a valid GeoJSON with styling, as produced by a [http://geojson.io/#map=15/37.7977/-122.4057 GeoJSON editor]. Kartographer supports the [https://github.com/mapbox/simplestyle-spec/tree/master/1.1.0</> simplestyle specification] with maki>Special:MyLanguage/Maps/Icons</>|Maki icons (Licensed under Creative Commons Zero).

Frames
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.


 * To insert a map without a frame, add the "frameless" attribute:
 * To add a caption, use the  attribute.

Note: Adding the text attribute automatically enables a frame, even if there is a  attribute.

==

<tvar|maplink></> also accepts an extra parameter "text" to specify link text instead of the coordinates:

The <tvar|maplink></> tag may contain the same geojson as <tvar|mapframe></>.

=== <tvar|maplink> </> attribute. Without this attribute, the coordinates will be shown (example: </> is set to the magic <tvar|minusnumber> </> or <tvar|minusletter> </> value. In this case each <tvar|minusnumber2> </> will be replaced with an incremental counter <tvar|onetwothree> </>, and <tvar|minusletter2> </> with <tvar|az> </> values.

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> </> will have different counter from <tvar|numberbar> </>.

It would make sense to use a distinct color for each counting group. All data added via <tvar|maplink></> will also be shown in all maps inserted with <tvar|mapframe></>, unless the <tvar|group> </> attribute is used.

could be expanded into

The attributes <tvar|zoom> </>, <tvar|latitude> </>, and <tvar|longitude> </> control the location of the popup map. Use <tvar|text> </> for the text of the link (could be any valid wikitext markup). Use <tvar|group> </> to add the contents of this tag to the named group (see below).

Groups
عالی

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></> tags, and one common map on the side of the page that shows them all.

The grouping concept allows editors to share data between multiple <tvar|mapframe></> and <tvar|maplink></> tags.

By default, the data inside the <tvar|mapframe></> or <tvar|maplink></> tag is shown only for that one tag, and will not be shown anywhere else.

If <tvar|mapframe></> or <tvar|maplink></> specify the <tvar|group> </> 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.

A tag may also show other groups, regardless if it belongs to a group or not, by specifying the <tvar|show> </> 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.

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

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 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.

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.

GeoShapes via Wikidata Query
<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(, ?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 <https://en.wikipedia.org/> . } GROUP BY ?id ?head ?headLabel ?link ?stateLabel "}

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 ''' https://query.wikidata.org/#... ''':

Map data from Commons

 *  Further information: 

Map data stored on Commons can be drawn on the map. For example, c:Data:Neighbourhoods/New York City.map: <mapframe width=300 height=400 zoom=11 latitude=40.7920 longitude=-73.9751> { "type": "ExternalData", "service": "page", "title": "Neighbourhoods/New York City.map" }

Combining multiple data types
<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" } } ] You can combine ExternalData, Feature, and FeatureCollection together in the same &lt;mapframe> or &lt;maplink> element:

<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      ]    }  } ] Map data from commons can be combined with other types of data:

Styling Wikidata ID elements
<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": "", "stroke": "#ffb100", "stroke-width": 8 } } For external data, you can also add styles and titles, using the properties keyword:

The main style keys are: "stroke" (color), "stroke-width", "stroke-opacity", "fill" (color), "fill-opacity".

Overlapping elements
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: <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 ] ] } } ] } 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: <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 ] ] } } ] }

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 showing the rendering of an example image with the same options.

Discovery Maps Update
The Discovery team structure changed in June 2017 and the ability for further map development has diminished; read more about the organizational update and the Discovery update on wiki.

Deploying mapframe on your site
 * Currently, we do not have the technical resources to deploy mapframe to any additional wikis. If a wiki wants to deploy mapframe on their site, they can do it on their own, similar to what the Swedish Wikipedia accomplished, by using the #Wikimedia-Site-requests process.


 * We also do not have the technical resources to do any minor bug fixes, feature requests or any other new deployments at this time. If severe bugs occur—such as maps aren't rendering from the tile servers—we will try our best to get them fixed.


 * If there are bugs or future feature requests for maps, please add them to the Phabricator board for possible future consideration. DTankersley (WMF) (talk) 23:08, 15 June 2017 (UTC)