Creating GeoJSON Map Overlays

What is GeoJSON?

GeoJSON is an open-source standard format for creating simple geographical features and non-spatial attributes on maps. It is based on the JSON format. With GeoJSON, you can represent points, line strings (streets, highways and boundaries), and polygons (countries, provinces, tracts of land).

Creating a GeoJSON file

In order to use GeoJSON on a map in your visual essay, you need a GeoJSON file. There are free, open-source GeoJSON files that can be found online, or you could create your own using this website: https://geojson.io.

Displaying GeoJSON shapes instead of markers

Many location entities in Wikidata can automatically be associated with a GeoJSON region in addition to the latitude and longitude coordinates. Adding the prefer-geojson attribute to the ve-map tag will result in the GeoJSON shape being used for Rome on the map instead of a marker.

<param ve-entity eid="Q220">
<param ve-map center="Q220" zoom="10" prefer-geojson>

Example map with a map title, custom base layer, 2 GeoJSON layers and an auto-generated marker with a Fontawesome icon and custom color.

<param title="Nicaragua" eid="Q811" fill="#92086D" marker-symbol="user">
<param ve-map title="Girolamo Benzoni's Accounts Refer to Cacao Being Grown in Nicaragua" center="12.316683, -84.946184" zoom="5" basemap="Esri_WorldPhysical">
<param ve-map-layer geojson active title="Central American Neotropics" url="Neotropics.geojson">
<param ve-map-layer geojson active title="Nicaragua" url="Nicaragua.geojson">

Using a custom GeoJSON map layer

One or more external GeoJSON files can be used as map layers. Each file is specified in a separate ve-map-layer tag.
The tag includes a geojson attribute identifying it as a GeoJson layer with a url attribute identifying the location of the GeoJSON file. In this example markers are displayed for the 100 largest cities in the world based on population data obtained from Wikidata.

<param ve-map zoom="2">
<param ve-map-layer geojson title="Worlds most populated cities" url="cities.json">

By default, points in a GeoJSON layer are displayed as standard markers. In some cases alternate syling may be desired, especially in cases where may points are displayed. In this example the same GeoJSON layer is used but the marker styling is customized in the ve-map tag.

<param ve-map
       zoom="2"
       marker-type="circle"
       radius="4" 
       stroke-width="0"
       fill="blue" 
       fill-opacity="1">
<param ve-map-layer geojson title="Worlds most populated cities" url="cities.json">

Using a GeoJSON map layer with time dimension

For GeoJSON data that is time tagged a time dimension extension is available for filtering and animatating location data based on date/time. The time dimension control is activated by including the time-dimension attribute in the ve-map tag. The time dimension control can configured using a number of optional attributes. The supported attributes can be seen on the help page.

<param ve-map 
       zoom="2"
       time-dimension
       time-interval="-008000/"
       duration="P10000Y"
       basemap="Esri_WorldGrayCanvas"
       max-zoom="4"
       date-format="YYYY"
       auto-play="true"
       auto-fit="false"
       fps="4"
       marker-type="circle"
       radius="4" 
       stroke-width="0"
       fill="blue" 
       fill-opacity="1">
<param ve-map-layer geojson
       title="Worlds most populated cities"
       url="cities.json">

For GeoJSON data that is time tagged a time dimension extension is available for filtering and animatating location data based on date/time. The time dimension control is activated by including the time-dimension attribute in the ve-map tag. The time dimension control can configured using a number of optional attributes. The supported attributes can be seen on the map documentation page.

<param ve-map 
       center="39.833333, -98.583333"
       zoom="4"
       time-dimension
       time-interval="1780/"
       duration="P500Y"
       basemap="Esri_WorldGrayCanvas"
       max-zoom="4"
       date-format="YYYY"
       fps="4">
<param ve-map-layer geojson title="US States" url="us-states.json">