Difference between revisions of "UCamGeoJSON"

From University Map Wiki
Jump to navigationJump to search
Line 15: Line 15:
 
* GeoJSON only provides geometry. UCamGeoJSON defines the recognized content of the '''properties''' element of [http://www.geojson.org/geojson-spec.html#feature-objects '''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.
 
* GeoJSON only provides geometry. UCamGeoJSON defines the recognized content of the '''properties''' element of [http://www.geojson.org/geojson-spec.html#feature-objects '''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).
+
* 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 [[#Inital map view|Initial map view]] below.
  
 
==Using UCamGeoJSON==
 
==Using UCamGeoJSON==

Revision as of 14:18, 13 December 2012

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.

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.

properties