UCamGeoJSON

From University Map Wiki
Jump to navigationJump to search

This is work in progress. Do not rely on this document just yet.
We expect to finalize this by the end of January 2013.

Introduction

In early 2013 we will be introducing a facility to annotate the University Map with your own information. Typically this will be done using a user interface, but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.

Note: if all you want to do is create a link to show your department etc on the map, you don't need to create any annotation. Just use the link shown in your browser address bar when you are looking at the full results for the institution. For example: http://map.cam.ac.uk/Department+of+Geography . This also means if you move, the link will show up to date information without any changes.

GeoJSON

Overlays are specified using UCamGeoJSON, a file format based on GeoJSON (see specification). UcamGeoJSON differs in three respects from GeoJSON:

  • GeoJSON only provides geometry. UCamGeoJSON defines the recognized content of the properties element of Feature objects, used to define what the shapes are for: things like colour of shapes, what text and icons are to appear at points, and so on.
  • Additional members of the top level JSON object z, pos and expand can be given, to set the initial view of the map (how far it is zoomed in, where it is centred, and whether it fills the browser window respectively). See Initial map view below.

Using UCamGeoJSON

The map is told to overlay custom annotation by giving it some UCamGeoJSON data in the URL. This is done in the fragment part of the URL (that is, the bit after a '#'), like this:

 http://map.cam.ac.uk/...#data

One can still include other parts of the URL as normal, for example to search for a particular institution. The whole of such URLs can be shortened using any shortening service, such as bit.ly.

The data can be included in one of three ways:

  • Directly including UCamGeoJSON in the URL. This is only appropriate for small amounts, as length of URLs that browsers and other software can handle is limited. In practice, restrict the total length of URLs to under 2,000 characters. In this case the first character after the hash will always be '{'. In general, do not (percent) escape this part of the URL: see escaping.
  • Referencing the UCamGeoJSON via a URL. The content provided by the URL is the UCamGeoJSON data, and the response to the request will use content-type 'application/json'. The URL will usually be absolute, that is start with 'http://', but in a few cases it may be relative to the map itself, and therefore start with a '/' (see especially Adapters below). For example:
 http://map.cam.ac.uk/#http://www.example.com/my-ucamgeojson.json
 http://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm

Do escape these embedded URLs properly, but don't double escape them.

  • Giving one, two or three numbers after the '#'. These are abbreviations for default zoom level, default map centre, or both, respectively (see below), thus:
 http://map.cam.ac.uk/#z
 http://map.cam.ac.uk/#lat,lon
 http://map.cam.ac.uk/#lat,lon,z

These are exactly equivalent to the following (respectively):

 http://map.cam.ac.uk/#{"z":z}
 http://map.cam.ac.uk/#{"pos":{"type":"Point","coordinates":[lat,lon]}}
 http://map.cam.ac.uk/#{"pos":{"type":"Point","coordinates":[lat,lon]},"z":z}

escaping

Normally, unusual characters in URLs are "percent escaped". However, whatever the right or wrong answer with the fragment part, in practice every browser handles this differently, and they also behave differently between pasting or typing a link into the address bar and following a link in a web page. Furthermore most pattern recognition for URLs will stop when they see a '{' in the fragment, so in emails, for example, verbatim JOSM will probably not link correctly (but you could do this via a bit.ly link).

The most reliable answer is

  • Don't escape the hash part at all.
  • Do escape URLs within the hash part as normal (but don't double escape them).

When you quote or follow such a link, some browsers escape some, but not all, unusual characters - but then present them to the code without un-escaping them; others un-escape some escaped characters! For this reason, in order to get consistent results, the map will treat %NN where N is a digit as a sequence to be un-escaped, but otherwise treat % as a true percent sign, except within URLs.

Initial map view

The top level GeoJSON object may additionally contain the members z, pos and expand to control the initial map view. Indeed, any or all of these may be the entire content of the object if all you want to do is override the default view determined by the map automatically.

  • z is the initial zoom level. For the University Map, the lowest zoom level (smallest scale, most zoomed out, when the scale on the map shows "2km") is 13 and the highest (largest scale, most zoomed in, when the scale shows "25m") is 19.
  • pos is the point on which the map is initial centred. The value of pos is a GeoJSON Point object, that is it provides a latitude and longitude on which the map is to be centred.
  • expand is a boolean value which (except for mobile devices with small screens) can be used to display the map with (false) the border content like the search box and search results list, or without (true) to fill the whole window.

For example:

 { "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},
   "z": 19,
   "type": "FeatureCollection",
   "features": [...] }

Properties

The content of the properties member of the GeoJSON Feature object is not defined by GeoJSON other than as a set of arbitrary key/value pairs. The intention is that these specify the appearance of the shapes described by the GeoJSON geometry.

UCamGeoJSON does define properties, as follows. In general the properties are a subset of CSS, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS for the details. Many of these are indeed simply applied as CSS styles to the graphic objects created in the HTML DOM.

In broad terms, the geometry provides filled areas, lines and points.

Areas and lines are drawn by applying a few styling properties, such as color (note US spelling, as in CSS).

Points are represented by icons (images) and/or text drawn at the position indicated according to the style indicated by the properties. You can have both an icon and text at a single point. These are grouped into an HTML div (hereinafter the box), which allows for flexible and controllable layout using CSS.

properties applied to filled shapes and lines

Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.

property name filled shapes lines notes
color colour with which the shape is filled colour in which the line is drawn any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc.
border, border-color, border-width the border styling, simple borders only n/a
opacity of the filled shape of the line

properties applied to both text and images

Namely, GeoJSON Point and MultiPoint objects.

Either text or an image or both may be displayed at a Point. This is done within a DIV box to which these properties are applied - see above.

The same content (typically several marker icons) is displayed for each point in a MultiPoint.

property name meaning
background, background-color the background of the box. Default is transparent.
border, border-color, border-width the border styling of the box. For text and icons, note that with judicious use of border images and backgrounds, one can produce things like "speech bubbles" pointing at the map, a-la-Google maps.
opacity of the background of the box
width, height of the box; if you only give width, that means you can have a box which all the text fits in, but wraps when too wide to fit across
overflow of the box contents, defaults to hidden
href url: the whole of the box content will link to the given url
top, left the box is offset by the amounts given. This means you can center the content over the point rather than at the default top left corner
padding around the inside of the box (pixels only)

properties applied to images/icons/markers

property name meaning
src url of icon (any image) to be displayed. Generally you will want this to have a transparent background and will typically use a PNG image. You could use an animated GIF if you insist! But probably not a JPG.

A few ready made icons and markers will be provided at http://map.cam.ac.uk/annotate/markers in due course.

float left, right: with both images and text floats the image to the left or right of the text within the box so the text wraps around it; otherwise the text starts underneath the image

properties applied to text

property name meaning
content Text string to be displayed. This is text, not HTML, and is encoded as UTF-8. If you need a line break, you need to provide it as a newline in the data (not <br/>). You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.
color colour of the text; any CSS colour specification is allowed, e.g. a name like green, #ccaa12, or rgb(12,128,44) etc.
font-family Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts.
font-size in pixels only, e.g. 12px
font-weight, font-style, text-decoration, letter-spacing, word-spacing, line-height per CSS
text-align center (US spelling), left, right within the box. This will also apply to any image which isn't floated.

Adapters

Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which convert data (identified via their query strings etc) into UCamGeoJSON.

Some default scripts are provided at http://map.cam.ac.uk/annotate/adapters:

  • University map, version 4: v4.json. version 4 applied limited annotation to its maps entirely within its URL query string; v4.json takes exactly the same query string and produces equivalent UCamGeoJSON.
  • GBN: gbn.json. Reads the OpenStreetMap XML file containing Granta Backbone network description. For example:
 http://map.cam.ac.uk/#/annotate/adapters/gbn.json

Other useful candidates would be: KML, GPX.

Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.

URL referencing considerations

Login-protected sources

Sometimes overlays may be located on sites which require a login, especially when these are confidential.

Note, however, that Dropbox in particular now offers unprotected URLs to shared files, so by advertising that URL one can store overlays in a Dropbox folder.

Where a resource is Raven protected (perhaps further restricted to a particular Lookup group of people), this will be detected and you will be asked to log in to Raven and try again. For generic links, we will indicate that you may have to log in,but cannot tell you where. Paste your link into the browser and complete the login there, then try the map URL again.

Because the content is accessed by the browser, which is what your login applies to, and not by the server, your content should be accessible once you have logged in.

Cross-site scripting

TBA