Maphub Open Annotation API Documentation

Abstract

This document describes how Maphub provides a Linked Data API by implementing the W3C Open Annotation specification. The provided examples demonstrate how the Open Annotation model could be used for representing annotations on digitized historic maps or high-resolution image material. They also show the use of Semantic Tags. The Maphub API currently provides access to two types of annotations:

Georeference Annotation: users create an annotation with the intention to express a correspondence between a point/region on the map and either a point/region in a defined geographic coordinate system or an authoritative Gazetteer. The goal of this type of annotation is to establish control points for raster image maps.
Commentarial Annotation: users associate textual information, tags, or links to thesaurus terms or Semantic Web resources, etc. with a point or region on the map. The goal of this type of annotation is to provide additional information about the map or map segment.

The definitions and examples in this document refer to Maphub version 0.3.

1. Introduction

Historic maps record historic geographic information and give insight into socio-economic and environmental phenomena such as land use, river channel changes or floods. They allow for the reconstruction of past urban environments and draw a picture of the cultural, political and religious context in which they were created. Their geographic accuracy tells us much about the state of technology at the time of their creation.

Scholars who study these maps often want to take notes on certain maps or map regions, view certain areas in the context of today’s maps, and associate map regions with historical events, places, or even people. By allowing them to annotate maps we allow them to express and share their knowledge with others. However, the historic maps that are currently published on the Web, mostly by libraries, don’t allow scholars or end-users to annotate them in a way that is interoperable across systems.

1.1 Background

Maphub is a Web portal for hosting digitized, high-resolution, historic maps. It allows users to annotate and contribute their knowledge about historic maps. It is currently being developed as part of the Open Annotation Collaboration. All user-contributed annotations are openly shared on the Web and represented in the W3C Open Annotation data model. Thereby they become Web resources that can be accessed by various clients simply by dereferencing HTTP URIs.

The current demo is bootstrapped with approximately 6000 public domain high-resolution map scans from the Library of Congress Historic Map division. A first concept screencast and the portal's source code are available. The portal is built using Ruby on Rails and reuses components (and algorithms) that were previously developed for the YUMA annotation framework. User-contributed annotations are linked with resources in other publicly available datasources, such as DBpedia and GeoNames.

1.2 Example

In the following examples we refer to a high-resolution scan of the Waldseemüller map. We keep a copy of the JPEG2000 digitized map file from the LoC Maps division at http://samos.mminf.univie.ac.at/maps/raw/g3200.ct000725C.jp2. The raw map image has a width of 18000 and a height of 10029 pixels.

Figure 1. Example Map.

Map images are usually converted into tile sets for online viewing and zooming. MapHub uses the magicktiler tool to create Zoomify tilesets from the original JP2 images. The tilesets now reside parallel to the original image files, e.g.: http://samos.mminf.univie.ac.at/maps/ts_zoomify/g3200.ct000725C.jp2. However, since tilesets represent a special view of the original map image, we can assume that the target of an annotation is always the original full-resolution map image file.

1.3 Namespaces

This document uses the following namespaces and prefixes to indicate those namespaces:

Prefix	Namespace URI	Description
`oa`	`http://www.w3.org/ns/openannotation/core/`	The core Open Annotation model
`oax`	`http://www.w3.org/ns/openannotation/extension/`	Interoperable extensions to the core model
`cnt`	`http://www.w3.org/2008/content#`	Representing Content in RDF
`dc`	`http://purl.org/dc/elements/1.1/`	Dublin Core Elements
`dcterms`	`http://purl.org/dc/terms/`	Dublin Core Terms
`foaf`	`http://xmlns.com/foaf/0.1/`	Friend of a Friend vocabulary terms
`rdf`	`http://www.w3.org/1999/02/22-rdf-syntax-ns#`	RDF vocabulary terms
`rdfs`	`http://www.w3.org/2001/01/rdf-schema#`	RDF Schema vocabulary
`ore`	`http://www.openarchives.org/ore/terms/`	OAI Object Reuse and Exchange

2. Georeference Annotations

A Georeference Annotation, as shown in Figure 2, associates a place URI (a Semantic Tag) with a place on the map (the annotation Target).

Figure 2. Example Georeference Annotation.

Place URIs are provided by the Geonames online gazetteer:

http://sws.geonames.org/2643743/: London, UK
http://sws.geonames.org/2517117/: Granada, ES
http://sws.geonames.org/2761369/: Vienna, AT

Georeference Annotations in Maphub are dereferenceable Web resources. When a client issues an HTTP GET request against the Georeference Annotation HTTP URI, Maphub determines the response format based on the value of the HTTP Accept header submitted by the client.

Figure 3 shows an example Georeference Annotation represented in the Open Annotation model. It can be retrieved by executing the following curl request:
curl -H "Accept: text/turtle" http://maphub.herokuapp.com/control_points/4

Figure 3. Open Annotation Georeference Annotation (Control Point)
Model Instance
Georeference Annotation - Turtle serialization @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . @prefix oa: <http://www.w3.org/ns/openannotation/core/> . @prefix foaf: <http://xmlns.com/foaf/spec/> . @prefix oax: <http://www.w3.org/ns/openannotation/extensions/> . @prefix dcterms: <http://purl.org/dc/dcmitype/> . @prefix dc: <http://purl.org/dc/elements/1.1/> . @prefix maphub: <http://maphub.info/ns/vocab#GeoReference> . <http://maphub.herokuapp.com/control_points/4> a maphub:GeoReference, oa:Annotation, oax:Tagging ; oa:annotated "2012-08-17T17:13:41Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ; oa:annotator <http://maphub.herokuapp.com/control_points/881c00ca-e892-11e1-a637-1231381d2be6> ; oa:generated "2012-08-17T17:13:41Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ; oa:generator <http://maphub.herokuapp.com> ; oa:hasTarget <http://maphub.herokuapp.com/control_points/8824e514-e892-11e1-a637-1231381d2be6> ; oax:hasSemanticTag <http://sws.geonames.org/2643743/> . <http://maphub.herokuapp.com/control_points/881c00ca-e892-11e1-a637-1231381d2be6> foaf:mbox "bernhard.haslhofer@cornell.edu" ; foaf:name "behas" . <http://maphub.herokuapp.com/control_points/8824e514-e892-11e1-a637-1231381d2be6> a oa:SpecificResource ; oa:hasSelector <http://maphub.herokuapp.com/control_points/88254b62-e892-11e1-a637-1231381d2be6> ; oa:hasSource <http://samos.mminf.univie.ac.at/maps/raw/g3200.ct000725C.jp2> . <http://maphub.herokuapp.com/control_points/88254b62-e892-11e1-a637-1231381d2be6> a oa:FragmentSelector ; rdf:value "xywh=6551,6231,1,1" . <http://samos.mminf.univie.ac.at/maps/raw/g3200.ct000725C.jp2> dc:format "image/jp2" ; a dcterms:StillImage .

Figure 3. Open Annotation Georeference Annotation (Control Point)

Model Instance

Georeference Annotation - Turtle serialization


        @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
        @prefix oa: <http://www.w3.org/ns/openannotation/core/> .
        @prefix foaf: <http://xmlns.com/foaf/spec/> .
        @prefix oax: <http://www.w3.org/ns/openannotation/extensions/> .
        @prefix dcterms: <http://purl.org/dc/dcmitype/> .
        @prefix dc: <http://purl.org/dc/elements/1.1/> .
        @prefix maphub: <http://maphub.info/ns/vocab#GeoReference> .

        <http://maphub.herokuapp.com/control_points/4>
            a maphub:GeoReference, oa:Annotation, oax:Tagging ;
            oa:annotated "2012-08-17T17:13:41Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ;
            oa:annotator <http://maphub.herokuapp.com/control_points/881c00ca-e892-11e1-a637-1231381d2be6> ;
            oa:generated "2012-08-17T17:13:41Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ;
            oa:generator <http://maphub.herokuapp.com> ;
            oa:hasTarget <http://maphub.herokuapp.com/control_points/8824e514-e892-11e1-a637-1231381d2be6> ;
            oax:hasSemanticTag <http://sws.geonames.org/2643743/> .

        <http://maphub.herokuapp.com/control_points/881c00ca-e892-11e1-a637-1231381d2be6>
            foaf:mbox "bernhard.haslhofer@cornell.edu" ;
            foaf:name "behas" .

        <http://maphub.herokuapp.com/control_points/8824e514-e892-11e1-a637-1231381d2be6>
            a oa:SpecificResource ;
            oa:hasSelector <http://maphub.herokuapp.com/control_points/88254b62-e892-11e1-a637-1231381d2be6> ;
            oa:hasSource <http://samos.mminf.univie.ac.at/maps/raw/g3200.ct000725C.jp2> .

        <http://maphub.herokuapp.com/control_points/88254b62-e892-11e1-a637-1231381d2be6>
            a oa:FragmentSelector ;
            rdf:value "xywh=6551,6231,1,1" .

        <http://samos.mminf.univie.ac.at/maps/raw/g3200.ct000725C.jp2>
            dc:format "image/jp2" ;
            a dcterms:StillImage .

3. Commentarial Annotations

Commenting on maps or map segments, as shown in Figure 4, is a major use case in Maphub. Users can select and then comment upon map regions. While the uer is writing their comments, the system proposes possibly relevant tags. These tags are in fact links to DBPedia, and therefore denoted as Semantic Tags. Accepted tags become part of the annotation.

Figure 4 shows an example commentarial map annotation created in Maphub.

The annotation can be retrieved by executing the following curl request: curl -H "Accept: text/turtle" http://maphub.herokuapp.com/annotations/4

Figure 4. Example Commentarial Annotation.

Figure 5 illustrates how this annotation is represented in the Open Collaboration Model. The annotation text is represented as anInline Body, and the semantic tags as Semantic Tags. Since the annotation is about part of the map resource, the annotation target is a Specific Target, which is further described by two Selector representations: one SVGSelector and a custom Selector that expresses the same information in the Well-known text (WKT) markup language, which is commonly used in geographic information systems.

Figure 5. Open Annotation Commentarial Annotation
Model Instance
Commentarial Annotation - Turtle serialization @prefix ct: <http://www.w3.org/2011/content#> . @prefix dcterms: <http://purl.org/dc/terms/> . @prefix foaf: <http://xmlns.com/foaf/spec/> . @prefix oa: <http://www.w3.org/ns/openannotation/core/> . @prefix oax: <http://www.w3.org/ns/openannotation/extensions/> . @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . <http://maphub.herokuapp.com/annotations/4> a oa:Annotation; oa:annotated "2012-07-18T02:03:58Z"^^<http://www.w3.org/2001/XMLSchema#dateTime>; oa:annotator <274c4218-d14b-11e1-b9b2-00163e110825>; oa:generated "2012-07-18T02:03:58Z"^^<http://www.w3.org/2001/XMLSchema#dateTime>; oa:generator <http://maphub.herokuapp.com>; oa:hasBody <275163a6-d14b-11e1-b9b2-00163e110825>; oa:hasTarget <2751d020-d14b-11e1-b9b2-00163e110825>; oax:hasSemanticTag <http://dbpedia.org/resource/Mediterranean_Sea>, <http://dbpedia.org/resource/Strait_of_Gibraltar>, <http://dbpedia.org/resource/Pillars_of_Hercules>, <http://dbpedia.org/resource/Gibraltar>, <http://dbpedia.org/resource/Atlantic_Ocean>, <http://dbpedia.org/resource/Classical_antiquity>, <http://dbpedia.org/resource/Ancient_history>, <http://dbpedia.org/resource/Ancient_Egypt>, <http://dbpedia.org/resource/Mediterranean_Basin> . <274c4218-d14b-11e1-b9b2-00163e110825> foaf:mbox "bernhard.haslhofer@cornell.edu"; foaf:name "behas" . <275163a6-d14b-11e1-b9b2-00163e110825> a ct:ContentAsText; dcterms:format "text/plain"; ct:chars "In antiquity, the Strait of Gibraltar (which connects the Atlantic Ocean with the Mediterranean Sea) was also known by the name \"The Pillars of Hercules\". This is the reason for this inscription!" . <2751d020-d14b-11e1-b9b2-00163e110825> a oa:SpecificResource; oa:hasSelector <2752261a-d14b-11e1-b9b2-00163e110825>, <27527570-d14b-11e1-b9b2-00163e110825>; oa:hasSource "http://samos.mminf.univie.ac.at/maps/raw/g3200.ct000725C.jp2" . <2752261a-d14b-11e1-b9b2-00163e110825> a ct:ContentAsText; dcterms:format "image/svg"; ct:chars """ <?xml version="1.0" standalone="no"?> <polygon xmlns="http://www.w3.org/2000/svg" points="5315,5639 5444,5529 5505,5593 5346,5691 5315,5639" /> """ . <27527570-d14b-11e1-b9b2-00163e110825> a ct:ContentAsText; dcterms:format "application/wkt"; ct:chars "POLYGON((5315 5639,5444 5529,5505 5593,5346 5691,5315 5639))" .

Figure 5. Open Annotation Commentarial Annotation

Model Instance

Commentarial Annotation - Turtle serialization

            @prefix ct: <http://www.w3.org/2011/content#> .
            @prefix dcterms: <http://purl.org/dc/terms/> .
            @prefix foaf: <http://xmlns.com/foaf/spec/> .
            @prefix oa: <http://www.w3.org/ns/openannotation/core/> .
            @prefix oax: <http://www.w3.org/ns/openannotation/extensions/> .
            @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

            <http://maphub.herokuapp.com/annotations/4> a oa:Annotation;
               oa:annotated "2012-07-18T02:03:58Z"^^<http://www.w3.org/2001/XMLSchema#dateTime>;
               oa:annotator <274c4218-d14b-11e1-b9b2-00163e110825>;
               oa:generated "2012-07-18T02:03:58Z"^^<http://www.w3.org/2001/XMLSchema#dateTime>;
               oa:generator <http://maphub.herokuapp.com>;
               oa:hasBody <275163a6-d14b-11e1-b9b2-00163e110825>;
               oa:hasTarget <2751d020-d14b-11e1-b9b2-00163e110825>;
               oax:hasSemanticTag <http://dbpedia.org/resource/Mediterranean_Sea>,
                 <http://dbpedia.org/resource/Strait_of_Gibraltar>,
                 <http://dbpedia.org/resource/Pillars_of_Hercules>,
                 <http://dbpedia.org/resource/Gibraltar>,
                 <http://dbpedia.org/resource/Atlantic_Ocean>,
                 <http://dbpedia.org/resource/Classical_antiquity>,
                 <http://dbpedia.org/resource/Ancient_history>,
                 <http://dbpedia.org/resource/Ancient_Egypt>,
                 <http://dbpedia.org/resource/Mediterranean_Basin> .

            <274c4218-d14b-11e1-b9b2-00163e110825> foaf:mbox "bernhard.haslhofer@cornell.edu";
               foaf:name "behas" .

            <275163a6-d14b-11e1-b9b2-00163e110825> a ct:ContentAsText;
               dcterms:format "text/plain";
               ct:chars "In antiquity, the Strait of Gibraltar (which connects the 
               Atlantic Ocean with the Mediterranean Sea) was also known by the name \"The Pillars
               of Hercules\". This is the reason for this inscription!" .

            <2751d020-d14b-11e1-b9b2-00163e110825> a oa:SpecificResource;
               oa:hasSelector <2752261a-d14b-11e1-b9b2-00163e110825>,
                 <27527570-d14b-11e1-b9b2-00163e110825>;
               oa:hasSource "http://samos.mminf.univie.ac.at/maps/raw/g3200.ct000725C.jp2" .

            <2752261a-d14b-11e1-b9b2-00163e110825> a ct:ContentAsText;
               dcterms:format "image/svg";
               ct:chars """
                <?xml version="1.0" standalone="no"?>
                     <polygon xmlns="http://www.w3.org/2000/svg"
                          points="5315,5639 5444,5529 5505,5593 5346,5691 5315,5639" />

                """ .

            <27527570-d14b-11e1-b9b2-00163e110825> a ct:ContentAsText;
               dcterms:format "application/wkt";
               ct:chars "POLYGON((5315 5639,5444 5529,5505 5593,5346 5691,5315 5639))" .

4. Annotation Index

Individual Georeference and Commentarial Annotations can be retrieved by dereferencing their HTTP URI, as shown before. To get a list of available annotations, Maphub offers two annotation indices; one for each annotation type. An annotation index is represented in the OAI Object Reuse and Exchange model. Figure 6 and 7 show the two indices currently exposed by Maphub.

An annotation index can be retrieved by executing the following curl request:
curl http://maphub.herokuapp.com/control_points.rdf
curl http://maphub.herokuapp.com/annotations.rdf

Figure 6. Georeference Annotation Index

Georeference Annotation Index - RDF/XML serialization

            <?xml version="1.0" encoding="utf-8"?>
            <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
                xmlns:ore="http://www.openarchives.org/ore/terms/"
                xmlns:dcterms="http://purl.org/dc/terms/"
                xmlns:dc="http://purl.org/dc/elements/1.1/"
                xmlns:foaf="http://xmlns.com/foaf/0.1/" >

                <rdf:Description rdf:about="http://maphub.herokuapp.com/control_points">
                    <rdf:type rdf:resource="http://www.openarchives.org/ore/terms/Aggregation"/>
                    <dc:title>Maphub Controlpoints</dc:title>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/1"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/2"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/3"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/4"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/9"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/10"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/11"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/12"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/13"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/control_points/14"/>
                </rdf:Description>

            </rdf:RDF>

Figure 7. Commentarial Annotation Index

Commentarial Annotation Index - RDF/XML serialization

            <?xml version="1.0" encoding="utf-8"?>
            <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
                xmlns:ore="http://www.openarchives.org/ore/terms/"
                xmlns:dcterms="http://purl.org/dc/terms/"
                xmlns:dc="http://purl.org/dc/elements/1.1/"
                xmlns:foaf="http://xmlns.com/foaf/0.1/" >

                <rdf:Description rdf:about="http://maphub.herokuapp.com/annotations">
                    <rdf:type rdf:resource="http://www.openarchives.org/ore/terms/Aggregation"/>
                    <dc:title>Maphub Commentarial Annotations</dc:title>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/annotations/1"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/annotations/2"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/annotations/3"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/annotations/4"/>
                    <ore:aggregates rdf:resource="http://maphub.herokuapp.com/annotations/5"/>
                </rdf:Description>

            </rdf:RDF>

5. References and Further Information

Haslhofer, B. Simon, R. Sanderson, R. Van de Sompel, H. (2011.) "The Open Annotation Collaboration (OAC) Model", Multimedia Tools and Applications, Springer, to appear: 2012

Simon, R. and Haslhofer, B. and Robitza, W. and Momeni Roochi, E.: Semantically Augmented Annotations in Digitized Map Collections. In: ACM/IEEE Joint Conference on Digital Libraries (JCDL), June 13-17, 2011, Ottawa, Ontario, Canada (2011)

A. Change Log

Date	Editor	Description
2012-07-20	behas	Maphub v.0.3 API documentation

This work is supported by the Open Annotation Collaboration and licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.