Help:Extension:Kartographer/Getting started

Main help pages:

How to create maps with Kartographer in VisualEditor
current: Introduction to Kartographer in wikitext
Kartographer - extensive help page

Overview

Kartographer is an extension to MediaWiki that allows you to create embedded maps and links to full-screen maps on wiki pages, as easily as writing a single line of wikitext or clicking on a menu item in the VisualEditor.

This guide focuses on maps in wikitext.

Some wikis wrap Kartographer's functionality in templates (often named Maplink and Mapbox). Check the Kartographer help page on your local wiki for commonly used templates.

Quick start: example

Downtown San Francisco

This code produces a simple 250x250 map in a frame, like the one you see in this section, with the caption "Downtown San Francisco".

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

Adding a map to a page

`‎<mapframe>`

To add a map that appears in a small window (or frame) on a wiki page, use the tag ‎<mapframe>. Clicking on the small map opens a full-screen interactive map.

On Wikipedia and other Wikimedia wikis, the embedded map is static. Clicking the static image opens a full-screen interactive map.
On Wikivoyage and test2wiki, this embedded map is interactive. Clicking, holding and moving the cursor pans the map; double-clicking or clicking the full-screen icon in the top corner opens a full-screen interactive map.

In its simplest form, ‎<mapframe> uses the following information to display a map of a specific area:

a location (latitude and longitude)
the size of the frame (width and height)

Example: <mapframe width=400 height=400 zoom=15 longitude=13.377704 latitude=52.516275 />

For a complete explanation of the syntax as well as a list of available attributes, see the main help page.

`‎<maplink>`

Instead of an interactive map on the wiki page itself, you can also create text (with an optional marker) that links to a fullscreen interactive map, using ‎<maplink>.

A minimal ‎<maplink> tag is even shorter -- all you need is a location.

Example: <maplink text="Downtown San Francisco" longitude=-122.3988 latitude=37.8013 />

Downtown San Francisco

For a complete explanation of the syntax as well as a list of available attributes, see the main help page.

GeoJSON

GeoJSON is a structured way of representing geographic information that uses the JSON standard.

A Kartographer map doesn't need any GeoJSON to work, but GeoJSON opens up a wide range of functionality that's not available in Kartographer alone, like markers, geoshapes from external sources like OpenStreetMap, special styling and more.

Composing GeoJSON

Regardless of whether you're creating your Kartographer-powered map in wikitext or the VisualEditor, you'll likely want to use a tool for composing your GeoJSON.

The GeoJSON.io editor is a great place to start, and there's this helpful guide.

What follows is a brief overview of commonly used powerful GeoJSON elements. For more in-depth coverage of the topic, see Help:Extension:Kartographer#GeoJSON and our full list of GeoJSON resources.

Markers

Instead of simply centering your map over the area you want to highlight, you can use GeoJSON to place one or more informative markers on your map.

To place a marker on your map, use the GeoJSON object "Feature". You can choose the marker's exact location on the map, the symbol used, its color and size, a title, a descriptive image, and more -- including whether to use letters or numbers across multiple markers.

The example below is a good starting place; for a comprehensive list of attributes and options, see the auto-counters section of the main help page.

Colorado State Capitol

<mapframe text="Colorado State Capitol" longitude="-104.98491" latitude="39.73939" zoom="17" width="250", height="250">
{  "type": "Feature",
   "properties": 
       { "marker-symbol": "town-hall", 
         "marker-color": "46ea5f", 
         "marker-size": "medium", 
         "title": "[[w:Colorado_State_Capitol|CO Capitol]]", 
         "description": "[[File:Coloradocapitolhill2.JPG|150px]]"
       },
    "geometry": 
       { "type": "Point", 
       "coordinates": [-104.98485267162323, 39.73928364167763] 
       }
}
</mapframe>

Shapes

GeoJSON allows you to draw shapes on top of a map. You can define simple shapes inline or import shape data from places like Wikidata and OpenStreetMap.

Though we include some illustrative examples below, much of this work is most easily done in a GeoJSON editor. If your wiki has VisualEditor enabled, refer to our guide to using VisualEditor to create maps or use this editor.

Inline

Using GeoJSON, Kartographer lets you define points (markers), lines and polygons to be drawn over your defined map area using special syntax and longitude/latitude coordinates.

<mapframe latitude="46.528635" longitude="-122.299805" zoom="6" width="246" height="272" align="right">
    {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.321777, 47.598526],
          [-122.629395, 45.505662]
        ]
}}]} 
</mapframe>

For more information, consult the Inline section of the main help page.

External data

In addition to displaying and marking up maps, Kartographer can also draw on the vast resources of geodata that Wikidata and OpenStreetMap have to offer. That data can help you highlight areas of your map using geoshapes, geographical data that describes the physical properties of an area.

Geoshapes can be rendered in three different ways, using the "service" attribute:

"service": "geopoint": Draws a marker.
"service": "geoline": Draws a simple line.
"service": "geoshape": Draws a polygon with a shaded interior.
"service": "geomask": Draws a polygon and shades everything outside the polygon.

Madagascar

A simple example:

<mapframe text="Madagascar" width=300 height=300 zoom=4 longitude=46.523 latitude=-19.86>
{
  "type": "ExternalData",
  "service": "geoshape",
  "ids": "Q1019"
}
</mapframe>

In addition to placing a single geoshape on your map, you can also use SPARQL queries to bring in several related geoshapes from Wikidata. (For help writing SPARQL, take a look at Wikidata's Query Builder.)

For more information, see the External data section of the main help page.

Further resources

The world of Kartographer maps and geographical data is large, and even our main help page can't cover every aspect of it. Consult this list of resources for more information.