Web mapping documents - Advancing geographic web maps in HTML

Plugin compatible with Leaflet 0.7

On the representation of geographical web maps in HTML

Treating HTML as what it is - an extensible markup language - theoretically allows us the thinking and expression of geographic concepts of maps - as well as concepts of maps making - directly within a  map. Think of geographical maps (and what constitutes them) being represented by a DOM. Then the idea of periodically archiving and reasoning about maps using software becomes feasible on a very detailed level. A computed map - in the respective state the user put the map in - can persisted as a DOM transformed into an e.g. JSON object consisting of all concepts and statements made in this map.

Modern web maps change over time and so does the DOM. Per location, per user, per browser session, per click on a category filter with deep linking. When we want to discuss the state and the future of interactive and participatory/adaptive/collaborative web maps - don't you agree that we could get to a deeper and more elaborate understanding about what kind of maps we actually make on on the web and with which tools? If so, we can establish new practices and change the format for cartographic research data to become a very specific type of document, simply through adapting the tools with which we make them.

HTML, as it is an extensible markup language, allows us the definition or integration of many different domain semantic vocabularies, e.g. the one on geography or cartography - if suitable current versions of such ontologies would (still) exist (see Lecture Notes of conferences on the the future of digital cartograpyh from the late '80s, when they still had fresh ideas on computational cartography!)

DMX is right there, in retrospective I can say that a more detailed understanding of hypertext combing with a better understandin of what the concept of a geographic map constitutes, is derived from my understanding of cultural comping networks as one can write with DeepaMehta (or DMX - The Context Machine), how it is now called.

The kick comes in when one understands how we currently talk witih kids about maps and teach them interpreting or reading maps nowadays in schools. Critical, reflective, reflexive map (see Gryl, 2011) reading is enabled by context information about each single information relevant for reading a complex system of information called a map.

There might be a fruitful intersection of concepts in critical cartography, post-reprsentational map theory (as it defines maps as a process) and not at least pedagogical practices ground on theories on human knowledge.

Harley (Deconstructing the Map, '89) suggests that we can also understand maps as texts. Which is where the ideas of reading maps as hypertext comes from. But the foundations of our current digital web maps doe not build on this knowledge a single bit.

Proof of Concept, Part 1

A Leaflet plugin integrating Schema.org und Dublin Core in Microdata Syntax (as HTML Extension Format directly onto the DOM elements representing elements of the map) to annotate Leaflet concepts in your geographic web map machine readable.

Visit the project page and please think of a contribution to the next version serializing the annotations to JSON-LD script tags in HTML (next to the DOM) - as this is nowadays the official format to exchange semantic annotations in web mapping documents as can be asynchronously parsed by Crawlers.

As part of a peer reviewed paper process I also wrote a concept proof in form of a spider which only extracts all microdata - persisting the map on disk only through the semantic annoations the geographic web map contains. It runs on the two example geographic web maps I authored with this Leaflet.annotate but will run on any other map created Leaflet.annotate (which runs).

Proof for the functionality of Laptop-Laboratory style of crawling microdata annotations from a dynamically generated DOM using Scrapy and Splash. Extracts all Schema.org annotations made on web map elements contained in the web mapping document. Facilitates reasoning on the dynamics of certain geographic web maps over time.

The proof demonstrates that, in fact, using only a one-man laptop environment operated crawler one can easily execute Javascript calls up to a depth that is enough to extract annotations from dynamically generated DOMs (by LeafletJS + Leaflet.annotate).

Plugin Documentation

The plugin extends the


Object for the following three standard elements in Leaflet: 

L.Marker, L.CircleMarker, L.Popup, L.ImageOverlay and L.GeoJSON

With this page you can easily use these map elements with Leaflet as always but can also author semantically annotated HTML and therewith machine readable web maps. While there is quite some effort already around the development of new geospatial data catalogs (which are awesome) this plugin turns the focus onto geographic web maps. Acknowleding that, de-facto, some maps already are data catalogs themselves, they are just not that well represented in HTML so that other programs can extract and re-use the information people collect in them.

Using this plugin you will contribute to research on digital cartography through allowing search engines and other applications (a) understand what is your map about, (b) what elements it is made of and (c) which parts of the world it explicitly deals with. Everything from just analyzing your maps representation in HTML.

Leaflet.annotate started as a plugin overriding the original HTML representation shipped by the open source web mapping library LeafletJS. It is a proof of concept implemtantion which effectively turned Leaflet into a semantic authoring environment for spatial data on the web. The hack turned out to integrate geospatial domain specific vocabulary into HTML creating advanced web mapping documents using the Microdata syntax, Dublin Core and Schema.org. 

Your web map elements when published with semantic markup can become geo-referenced "resource descriptions", which in turn are:

  • identifiable and addressable for others,
  • discoverable for users through search engines,
  • interoperable items for other application developers,
  • collections of linked data and therewith and
  • potentially multilingual without much additional effort.

Therefore we wrote this small script, integrating freeing you of caring much about the necessary syntax details.

Your feedback or contributions are very welcome. Please use this issue tracker to report any issues you experienced with it.

Overview & installation

The source code released contains two different components, one (the core) for generating the semantic markup and the other (an example) for reading and making the markup usable for visitors who want to systematically read and explore the map

  1. The core file is the semantic markup generating Leaflet Plugin in


    After loading this script you can start annotating Marker, CircleMarker, Popup, ImageOverlay and GeoJSON elements.

  2. The first add-on is a custom L.control which uses the semantic markup generated by the core, it can be installed through loading the files

    util/Leaflet.annotate.Viewer-0.3.0.min.js and 

    Using this add-on you can add a text based search control to your map allowing readers of it to magically listsearch and focus all your annotated web map elements.

To assist you in the creation of valid semantic markup you can find existing JavaScript objects which help you to map user input to valid Schema.org type names (=Leaflet.annotate's itemtype option). These type names also allow you to map a label in your language to the schema.org type name.

  • util/Leaflet.annotate.types_en_US.js
  • util/Leaflet.annotate.types_de_DE.js

Example: Photos of sculptures in Paris

Browse this example showing public sculptures in Paris.

This map is a good example of a so called "map mashup". In it you'll just find geo-referenced pictures representing public sculptures in the city of Paris. All web map elements are annotated as representing a Photographs depicting a specific contentLocation.

Here is the Leaflet code which produces the semantic markup explorable in the example. Bold elements are interpreted by the annotate plugin to produce proper markup.

L.circleMarker(coordinates, { weight: 2, opacity: 0.6, fillColor: "#a9a9a9",
  fillOpacity: 0.2, lineCap: 'square', color : "#8f1414",
  alt: "Photo of a sculpture named " + popupTitle,
  itemtype: 'Photograph',   geoprop: 'contentLocation',
  url: photoURL, title: 'Picture of ' + popupTitle

If you copy & paste the generated markup into Googles Structured Data Testing Tool you will find out that it can identify/recognize ~400pictures were composed in this map.

The data for this map is fetched live with SPARQL from query.wikidata.org. Sculptures are shown when they are located in Paris (or one of its districts) and have a publicly licensed picture associated in wikmedia commons. The semantic annotation of the CircleMarker elements here happens in the SVG fragment created by Leaflet and, according to the standard, in a metadataelement.

Example: Annotated GeoJSON-Layer

Browse this example to see the USA with "charmingly inaccurate" boundaries.


Automatic Annotation

Annotation happens automatically whenever you add a MarkerCircleMarkerPopup or ImageOverlay to your L.map and pass them a valid itemtype value as an option to Leaflets Standard API:

L.marker(coordinates, {
  title: 'Madison Square Garden', itemtype: 'CivicStructure'

Valid itemtype values are currently all the names of Schema.org terms which allow for at least one Place as one of their properties. Regarding the schema.org type you use you might be required to explicitly specify the desired geoprop option

L.circleMarker(coordinates, { title: 'The Catcher in the Rye', itemtype: 'Book', geoprop: 'locationCreated', sameAs: 'https://www.wikidata.org/wiki/Q183883' })

For example when mapping CreativeWorks you can express a geographical dimension for the location it was created (locationCreated) or for the location it depicts (contentLocation) using the respective property names.

Here is another, more comple example, annotating an ImageOverlay:

L.imageOverlay(imageUrl, imageBounds, {
  "itemtype": "CreativeWork", "geoprop": "contentLocation",
  "publisher": "The University of Texas",
  "source": "https://www.lib.utexas.edu/maps/new_jersey.html",
  "created": "Thu Jan 01 1920 01:00:00 GMT+0100 (CET)",
  "title": "Automobile Blue Book"

Manual Annotation

On a GeoJSON element annotation happens whenever you call the .annotate() method on the GeoJSON layer and pass a valid code>itemtype value as an option:

L.geoJson(geojsonData, { title: 'Uganda',   itemtype: 'Country',   sameAs: 'https://www.wikidata.org/wiki/Q1036' }).annotate()

This will markup the GeoJSON document as a map overlay representing the area for the Republic of Uganda. In Wikidata the URI for the concept/entity representing this country is https://www.wikidata.org/wiki/Q1036.

Another example of a semantically annotated GeoJSON overlay where the options used by Leaflet.annnotate to generate the semantic markup are highlighted in bold:

// 1. Markup your GeoJSON
var statesBoundaries = L.geoJson(geoJsonData, {
  title: 'Charmingly Inaccurate - USA', itemtype: 'Country',
  description: 'A caricature of the lower 48 United States, this linework 
    set is recognizable and friendly, but not concerned with accuracy. It’s
      that friend you have who’s always embellishing his stories.
         You never mind his lying, though, because the exaggerations make
           things more fun. Go ahead, enjoy the story your map is telling.
             (Version 1.1)',
  creator: 'Daniel P. Huffmann', publisher: 'Daniel P. Huffmann',
  published: '10/04/2013', modified: '10/04/2013', created: '3/24/2013',
  rights: 'Public Domain',
  derivedFrom: 'Derived from a 1920 broadside map entitled “The Rights of 
    the People—Women are People: Suffrage Victory Map. Equal Suffrage
      League of Virginia Papers, Acc. 22002,Library of Virginia.'

// 2. Render annotations into the DOM

API Documentation

You can find all options with which the Leaflet.annotate plugins extends the Standard API documented in the API section of the projects README.