https://wiki.cam.ac.uk/wiki/university-map/api.php?action=feedcontributions&user=dje39&feedformat=atom
University Map Wiki - User contributions [en]
2024-03-29T10:29:02Z
User contributions
MediaWiki 1.39.4
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=749
Map Annotation
2023-03-06T12:05:23Z
<p>dje39: Raven login => University login</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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: https://map.cam.ac.uk/Department+of+Geography . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also if you only want to put some pins on the map, you can do this directly from the map: click where you want them and choose the pin icon (draw marker). Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another https URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (University login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>https://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [https://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server (University login required). Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [https://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>https://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
https://map.cam.ac.uk/#https://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[https://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a University login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your University login and the identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io dillinger.io]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL and is served over https. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link, Hover & Pop-up ====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the ''Markdown'' box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io/ dillinger.io].<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mind some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=748
Map Annotation
2023-03-06T12:04:56Z
<p>dje39: Raven login => University login</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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: https://map.cam.ac.uk/Department+of+Geography . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also if you only want to put some pins on the map, you can do this directly from the map: click where you want them and choose the pin icon (draw marker). Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another https URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (University login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>https://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [https://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server (University login required). Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [https://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>https://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
https://map.cam.ac.uk/#https://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[https://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a University login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io dillinger.io]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL and is served over https. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link, Hover & Pop-up ====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the ''Markdown'' box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io/ dillinger.io].<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mind some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=747
Map Annotation
2023-03-06T12:04:27Z
<p>dje39: Raven login => University login</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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: https://map.cam.ac.uk/Department+of+Geography . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also if you only want to put some pins on the map, you can do this directly from the map: click where you want them and choose the pin icon (draw marker). Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another https URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (University login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>https://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [https://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server (University login required). Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [https://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>https://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
https://map.cam.ac.uk/#https://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[https://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io dillinger.io]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL and is served over https. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link, Hover & Pop-up ====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the ''Markdown'' box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io/ dillinger.io].<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mind some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=746
Map Annotation
2023-03-06T12:03:39Z
<p>dje39: Raven login => University login</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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: https://map.cam.ac.uk/Department+of+Geography . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also if you only want to put some pins on the map, you can do this directly from the map: click where you want them and choose the pin icon (draw marker). Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another https URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (University login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>https://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [https://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [https://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>https://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
https://map.cam.ac.uk/#https://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[https://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io dillinger.io]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL and is served over https. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link, Hover & Pop-up ====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the ''Markdown'' box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io/ dillinger.io].<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mind some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Database_API&diff=743
The Database API
2020-03-27T11:57:27Z
<p>dje39: /* institution */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use this API.<br />
<br />
This page describes version 6 of the API, made live on February 20, 2013.<br />
<br />
Version 5 ([[The_Database_API_v5|old documentation]]) has been withdrawn. You can see a [[The_Database_API_v6_changes|summary of changes from version 5]].<br />
<br />
There is an experimental [[Python Database API interface]] if you want to work with this API from Python.<br />
<br />
==Introduction==<br />
<br />
The same information as provided by the [[The Map URL API]] is provided in machine readable form using URLs like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>q=''search''[&amp;partial=yes]<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>bb=''boundingbox''<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>ref=''ref''<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>inst=''inst''<br />
<br />
with the same interpretation as in [[The Map URL API]] (note that one=list is not relevant in the q= and bb= variants, and the simple&nbsp;<em>name </em>variant is not available to the API - just use <strong><nowiki>http://map.cam.ac.uk/v6.json?</nowiki>q=<em>name</em></strong>).<br />
<p><br />
An additional option <strong>?limit=<em>limit</em></strong> is also available on the ?q and ?bb forms which limits the number of results returned to the number given. For example</p><br />
<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>q=saint&amp;limit=15<br />
<br />
Values of query parameters, such as <strong>?q=</strong> are limited to 2,000 characters. For <strong>?inst=</strong> and <strong>?ref=</strong> queries, a maximum of 25 may be requested at once (separating the requested codes with '|').<br />
<br />
<p>Also, there is another query type available to the database API not available when using a consumer URL. <strong>?alpha=<em>letter</em></strong> will provide an alphabetically ordered listing of the entire institution database for that letter. This is used as the basis for the directory page and other alphabetic listings. Please cache the results of this search so that it does not place an unwarranted load on the database. You can also filter by type, for example:</p><br />
<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>alpha=s&amp;filter=college<br />
<br />
<p>The version 6 API also supports discovery and navigation around the reference hierarchy. See [[The Database API reference discovery]] for more details. In addition, the [https://map.cam.ac.uk/refbrowser/ interactive browser] (also linked from the 'More...' menu) can be useful when exploring the data available and when identifying the various codes used.</p><br />
<br />
<p><br />
The &#39;v6&#39; is a version number, allowing for potential backward compatibility if we change the spec at some point in the future. Only v6 is useful for now. v5 was deprecated in January 2013 and backward compatibility was not provided.</p><br />
<p><br />
The &#39;json&#39; part indicates the results are provided in JSON format. We may produce other formats in future, in which case URLs such as&nbsp;<strong><nowiki>https://map.cam.ac.uk/v6.xml?</nowiki>...</strong> would be introduced, but for the time being, only JSON is supported.</p><br />
<p><br />
The result is a JSON array:</p><br />
<p style="margin-left: 40px; "><br />
[ { &quot;type&quot;: <em>type0</em>, ... }, { &quot;type&quot;:&nbsp;<em>type1</em>, ...<em>&nbsp;</em>}, ... ]</p><br />
<p><br />
where each object in the array is an entity matching the request.&nbsp;If there are <strong>no results</strong>, an empty array is produced. If there is <strong>only one result</strong>, it is still provided as an array (of one object), not as just the object. Note also that requests by inst and ref may occasionally also yield more than one result. </p><br />
<p><br />
The content of the rest of each object depends on:</p><br />
<ul><br />
<li><br />
<em>type</em></li><br />
<li><br />
what information is available for each result</li><br />
<li><br />
whether the request was a search (q=... or <em>name</em>) or direct look up (ref or inst URLs)</li><br />
</ul><br />
<p><br />
<i>type</i>&nbsp;is one of:</p><br />
<p style="margin-left: 40px; "><br />
<strong>error<br /><br />
institution<br /><br />
site<br /><br />
college</strong><br /><br />
<strong>building<br /><br />
entrance</strong><br /><br />
<strong>nonuniversity</strong><br /><br />
<strong>virtualsite</strong><br /><br />
<strong>street</strong><br /><br />
<strong>more</strong></p><br />
<br />
==Error reports==<br />
<br />
<p><br />
If <em>type</em> is <strong>error</strong>, then the http request will also return an appropriate status code, typically 400 indicating the request is malformed (wrong combination of query parameters, for example) or 404 (api version or format not implemented for example). The consumer should also be prepared to handle other HTTP errors generated by the server which will not provide JSON data (500 for example). Apart from these, all correctly formed requests will generate status 200. Note that this includes requests with no results (which produce an empty array).</p><br />
<p><br />
Note also that if you mis-spell &#39;v6.json&#39; (for example, say you incorrectly use a capital V), then the URL may be interpreted as the end-user form M:/<em>name</em> so you would get a stream of HTML!</p><br />
<br />
<p>v5.json, the now deprecated API, will always produce an error like this (actually an HTTP 410 error).</p><br />
<br />
==Entity structure==<br />
<p><br />
Contents of JSON objects representing entities found are as follows, by type.</p><br />
<br />
<p>In general, each request includes information about things linked to each result: the buildings for an institution, the entrances to a site and so on. This referencing only applies one level deep: those parts are excerpted: they do not themselves contain further entities to which they refer. If you need these, you would have to request the content by ref or inst from the parent. The fields omitted in the second level are indicated with an asterisk in the tables that follow.<br />
<br />
===error===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>error</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
code</td><br />
<td><br />
the HTTP status code</td><br />
<td><br />
int</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
error</td><br />
<td><br />
text describing the error</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===more===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>more</strong></td><br />
<td><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><br />
<td><br />
When the number of results is limited by <strong>?limit=<em>limit</em></strong>, the last element in the array of results may indicate "more", that there are more results that could be found but the limit was reached. Because certain results are redacted in some circumstances, note that the number of elements in the array may be fewer than limit+1 even if the limit is reached. "more" is not included if all the available results are returned. There isn't any way to page through the results: the search needs to be made more specific.</td><br />
</tr><br />
</table><br />
<br />
===institution===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>institution</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
inst</td><br />
<td><br />
the institution code of the entity</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
role</td><br />
<td><br />
kind of institution</td><br />
<td><br />
string, one of:<br /><br />
college<br /><br />
academic<br /><br />
admin<br /><br />
nonacademic<br /><br />
mrc<br /><br />
library<br /><br />
museum<br /><br />
cafe<br /><br />
lecture</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
prefix</td><br />
<td><br />
the name prefix</td><br />
<td><br />
string</td><br />
<td><br />
for example, &#39;Department of&#39;, &#39;Centre for&#39;</td><br />
</tr><br />
<tr><br />
<td><br />
name</td><br />
<td><br />
the substantive part of the institution name</td><br />
<td><br />
string</td><br />
<td><br />
for example, &#39;Geography&#39;. This is the field to sort on for alphabetically ordered institutions</td><br />
</tr><br />
<tr><br />
<td><br />
suffix</td><br />
<td><br />
the name suffix</td><br />
<td><br />
string</td><br />
<td><br />
often an acronym or former name, which would often be presented in parentheses. For example, when name is &#39;Advanced Photonics and Electronics&#39;, prefix is &#39;Centre for &#39; and&nbsp;suffix would be &#39;CAPE&#39;. The whole might be presented as &#39;Advanced Photonics and Electronics (CAPE), Centre for&#39; or &#39;Centre for Advanced Photonics and Electronics (CAPE)&#39;</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
when the entity is subsidiary to another, this is the institution code of the parent institution</td><br />
<td><br />
entity</td><br />
<td><br />
for example the faculty of a department</td><br />
</tr><br />
<tr><br />
<td><br />
options</td><br />
<td><br />
arbitrary space separated tokens indicating arbitrary options</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
sd</td><br />
<td><br />
the subdomain of the entity</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;lucy-cav&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
info</td><br />
<td><br />
contact information (etc)</td><br />
<td><br />
array of objects (see below)</td><br />
<td><br />
<p><br />
for example:</p><br />
<p><br />
&nbsp;&nbsp;"info":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"founded",&nbsp;"founded":&nbsp;"1505"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"address",&nbsp;"address":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"street",&nbsp;"street":&nbsp;"St&nbsp;Andrew's&nbsp;Street"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"place",&nbsp;"place":&nbsp;"Cambridge"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"postcode",&nbsp;"postcode":&nbsp;"CB2&nbsp;3BU"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{"type":&nbsp;"location",&nbsp;"location":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"college",&nbsp;"ref":&nbsp;"CHRISTS",&nbsp;"name":&nbsp;"Christ's&nbsp;College",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.206145,&nbsp;"lon":&nbsp;0.122944,&nbsp;"primitive":&nbsp;"w",&nbsp;"id":&nbsp;147488000<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br/><br />
&nbsp;&nbsp;]</p><br />
<br />
<p>Note that all this contact information relates to the entity concerned. Subordinate entities will have their own contact information if relevant.</p><br />
</td><br />
</tr><br />
<tr><br />
<td><br />
sortasvia</td><br />
<td><br />
when result matched via an AKA field (see below) or from a role, the index of the info element which it matched against</td><br />
<td><br />
integer</td><br />
<td><br />
<td></td><br />
</tr><br />
</table><br />
<br />
===virtualsite===<br />
<br />
'virtualsite' entities are '''''only''''' returned as part of [[The Database API reference discovery]] process in response to a search with 'ref=*' or 'ref=''SITE''/*'. These are just like sites and subsites except that they have no location information associated with them. They exist only so that the complete set of prefix letters (including those for buildings not on any real site) is available as a starting point for reference discovery (see the documentation for details). Looking up their ref verbatim will yield no result.<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td>type</td><br />
<td><strong>virtualsite</strong></td><br />
<td></td><br />
<td></td><br />
</tr><br />
<br />
<tr><br />
<td>ref</td><br />
<td>the reference of the entity</td><br />
<td>string</td><br />
<td>e.g. "K", "EXT/BEAUFORT"<br /><br />
See [[The Database API reference discovery]] for a discussion of reference formats</td><br />
</tr><br />
<br />
<tr><br />
<td>name</td><br />
<td>the name of the entity (assuming it has one)</td><br />
<td>string</td><br />
<td>"north city"</td><br />
</tr><br />
<tr><br />
<td>nonuniversity</td><br />
<td>key only present if the virtual site is not part of the university estate but where we want to refer to it in the map</td><br />
<td>boolean</td><br />
<td>always '''true''' if present. Currently the only virtual non-university site has reference 'EXT', along with some virtual sub-sites of 'EXT'</td><br />
</tr><br />
</table><br />
<br />
===Fields common to all geographical objects===<br />
<br />
The remainder are all geographical objects and share the following common fields:<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
ref</td><br />
<td><br />
the reference of the entity</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;H/FORVIE&quot;<br /><br />
See [[The Database API reference discovery]] for a discussion of reference formats,<br />
</td><br />
</tr><br />
<tr><br />
<td><br />
name</td><br />
<td><br />
the name of the entity (assuming it has one)</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;Forvie Site&quot;, &quot;Austin Building&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
lat</td><br />
<td><br />
the latitude of a representative position of the entity</td><br />
<td><br />
float</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
lon</td><br />
<td><br />
the longitude of a representative position of the entity</td><br />
<td><br />
float</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
primitive</td><br />
<td><br />
whether the building was derived from an OSM way (&quot;w&quot;) or node (&quot;n&quot;)</td><br />
<td><br />
string (either &quot;w&quot; or &quot;n&quot;)</td><br />
<td><br />
primitive and id can be used together to form a link to the OSM browser, as in http://osm.org/browse/way/1234567</td><br />
</tr><br />
<tr><br />
<td><br />
id</td><br />
<td><br />
the OSM id of the node or way from which the entity was derived</td><br />
<td><br />
int</td><br />
<td><br />
sites, colleges and buildings are usually areas (ways) in OSM, though there are a few "buildings" which represent an office in larger, possibly non-university premises, represented just as a node. Complex buildings, e.g. one containing 'holes', are represented as OSM 'multipologon relations'. In these cases the referenced way will be the one corresponding to the outside of the building - the holes can be accessed via the relation containing this way and OSM tags relating to the building will be associated with the outer way or the relation (but not both).<br/>&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===site===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>site</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
nonuniversity</td><br />
<td><br />
<strong>true</strong></td><br />
<td><br />
boolean</td><br />
<td><br />
present to distinguish non-university sites from university sites (currently the only non-virtual, non-university site is 'H', the Cambridge Biomedical Campus)</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
when the site is a sub-site, this is the main site</td><br />
<td><br />
site object</td><br />
<td><br />
for example object for &quot;Cambridge Biomedical Campus&quot; when name is &quot;Forvie Site&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
entrances*</td><br />
<td><br />
to the site</td><br />
<td><br />
array of entrance objects</td><br />
<td><br />
see below</td><br />
</tr><br />
</table><br />
<br />
===college===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>college</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
This is the geographical entity for a college site or sub-site, not the institutional information which is an inst. This is very similar to&nbsp;<strong>site</strong>.</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
when the college item is a subsidiary site, the main site</td><br />
<td><br />
college object</td><br />
<td><br />
e.g. object for &quot;Magdalene College&quot; when site is ref MAGD/CRIPPS</td><br />
</tr><br />
<tr><br />
<td><br />
entrances*</td><br />
<td><br />
as for site</td><br />
<td><br />
array of entrance objects</td><br />
<td><br />
see below</td><br />
</tr><br />
<tr><br />
<td><br />
institution*</td><br />
<td><br />
the institution information associated with this college area</td><br />
<td><br />
institution object</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===building===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>building</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
site/college in which the building is situated</td><br />
<td><br />
site/college object</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
entrances*</td><br />
<td><br />
entrances of the building</td><br />
<td><br />
array of entrance objects</td><br />
<td><br />
see below</td><br />
</tr><br />
<tr><br />
<td><br />
occupants*</td><br />
<td><br />
occupants of the building</td><br />
<td><br />
array of institution objects</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===entrance===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>entrance</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
entrances apply to sites and colleges as well as buildings. Note, entrances are always derived from OSM node entities.</td><br />
</tr><br />
<tr><br />
<td><br />
parents*</td><br />
<td><br />
buildings and/or sites/colleges to which this entrance gives access</td><br />
<td><br />
array of building/site/college objects</td><br />
<td><br />
note that a few entrances give access to university properties on either side; also occasionally an entrance to a building isn&#39;t actually part of the building footprint.</td><br />
</tr><br />
<tr><br />
<td><br />
occupants*</td><br />
<td><br />
the institutions that gain access by this entrance</td><br />
<td><br />
array of institution objects</td><br />
<td><br />
OK, you don&#39;t exactly &quot;occupy&quot; an entrance, but consistent with buildings</td><br />
</tr><br />
<tr><br />
<td><br />
direction</td><br />
<td><br />
the direction of a normal to the parent building/site/college at an entrance, in degrees between -180 and 180&nbsp;measured anticlockwise from the east (positive x axis) pointing away from the building</td><br />
<td><br />
float</td><br />
<td><br />
the direction can be used to orient an overlaid arrow pointing to the entrance.</td><br />
</tr><br />
<tr><br />
<td><br />
user</td><br />
<td><br />
some or all of the letters &quot;fbvg&quot;</td><br />
<td><br />
string</td><br />
<td><br />
standing for &quot;foot&quot;, &quot;bicycle&quot;, &quot;vehicle&quot; and &quot;goods&quot; respectively, indicating the class or classes of users which can use the entrance.</td><br />
</tr><br />
<tr><br />
<td><br />
door</td><br />
<td><br />
&nbsp;</td><br />
<td><br />
boolean</td><br />
<td><br />
whether this entrance is the door to a building (true) or a gate to a site (false)</td><br />
</tr><br />
</table><br />
<br />
===nonuniversity===<br />
<br />
Non-university objects are only provided no reference is available. Where they have a University reference they are included in the general scheme of sites and buildings, with the '''nonuniversity''' element set to '''true'''.<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<b>nonuniversity</b></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
role</td><br />
<td><br />
what kind of thing this is</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;hotel&quot;</td><br />
</tr><br />
</table><br />
<br />
===street===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<b>street</b></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
no additional fields other than the common ones</td><br />
</tr><br />
</table><br />
<br />
==Contact information==<br />
<br />
Contact information for institutions and colleges is grouped into an array of items each of which may be repeated and qualified as necessary. For example, multiple phone numbers with descriptions of what each is for.&nbsp;Note that these all relate to the entity concerned. Subordinate entities will have their own contact information if relevant, so addresses, phone numbers etc. for child institutions should not be given as alternate addresses within the same info array.<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
person</td><br />
<td><br />
string</td><br />
<td><br />
primary contact named individual, for example &quot;Prof. John Doe&quot;.</td><br />
</tr><br />
<tr><br />
<td><br />
description</td><br />
<td><br />
string</td><br />
<td><br />
A brief description of the function of the institution</td><br />
</tr><br />
<tr><br />
<td><br />
title</td><br />
<td><br />
string</td><br />
<td><br />
primary contact title, for example &quot;The Bursar&quot;, where useful for more personal addressing.</td><br />
</tr><br />
<tr><br />
<td><br />
address</td><br />
<td><br />
array of objects (see below)</td><br />
<td><br />
<p><br />
postal address (assumed to be the primary address if not described otherwise by the role attribute - see below).</p><br />
</td><br />
</tr><br />
<tr><br />
<td><br />
phone</td><br />
<td><br />
string</td><br />
<td><br />
in the international form +44 1223 33nnnn</td><br />
</tr><br />
<tr><br />
<td><br />
fax</td><br />
<td><br />
string</td><br />
<td><br />
ditto</td><br />
</tr><br />
<tr><br />
<td><br />
email</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
url</td><br />
<td><br />
string</td><br />
<td><br />
complete, including the http://</td><br />
</tr><br />
<tr><br />
<td><br />
founded</td><br />
<td><br />
int</td><br />
<td><br />
(colleges only) year of foundation</td><br />
</tr><br />
<tr><br />
<td><br />
logo</td><br />
<td><br />
string</td><br />
<td><br />
url of image which is used to brand the institution</td><br />
</tr><br />
<tr><br />
<td><br />
twitter</td><br />
<td><br />
string</td><br />
<td><br />
twitter handle including the @, e.g. @camgeog</td><br />
</tr><br />
<tr><br />
<td><br />
facebook</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
AKA</td><br />
<td><br />
string</td><br />
<td><br />
another name or search term by which the institution is known. Unlike other info fields, the value of this info item is (usually) added to the search index.<br />
<br />
<p>This may be used in different ways according to the accompanying options. An "xm" option excludes the entry from the paper map (this might be a very old name, for example, which you want search results to hit, but not include in an up-to-date static map). "xw" excludes it from the web site searches and presentation, but includes it in the paper map and other alphabetic listings. "xd" excludes it from presentation (the user doesn't see it), but includes it in the index.</p><br />
<br />
<p>Additionally when a ?q returns a result via a match on an AKA, the top level structure contains 'viaaka', the index of the info element which it matched against. This is so that you can tell the user if you want to why their search matched when it doesn't appear to match the main entry name.</p></td><br />
</tr><br />
<tr><br />
<td><br />
subsection</td><br />
<td><br />
string</td><br />
<td><br />
indicates that all the entries that follow up to a subsection-end entry or another subsection entry or the end of the info array are grouped together. This would typically be used where an institution lists contact details for a well-defined part or function of the institution - for example, the phone, fax and email for the Box Office part of the ADC Theatre. A consumer would typically render the subsection string as a subheading of some kind and possibly indent its contents or separate them out in some suitable way. (note: this supersedes the version 5 method of grouping, where repeated roles indicated subsections, which was rather clumsy and prevented the individual elements having their own roles).</td><br />
</tr><br />
<tr><br />
<td><br />
subsection-end</td><br />
<td><br />
string (unused)</td><br />
<td><br />
explicitly terminates a group of subsection elements.</td><br />
</tr><br />
</table><br />
<br />
===Contact information qualifiers===<br />
<br />
Each of these objects contains a type to identify the key, and may also contain other qualifying information, as follows:<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
one of the keys listed in the previous table</td><br />
<td><br />
</td><br />
</tr><br />
<tr><br />
<td><br />
role</td><br />
<td><br />
string</td><br />
<td><br />
description of what the contact information will be used for. If omitted, assumed to be the primary contact information of this type. For URLs this would typically be used for the link text rather than displaying the URL itself. For others it would serve as a caption.&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
options</td><br />
<td><br />
string</td><br />
<td><br />
arbitrary space separated string of options (meanings client dependent)</td><br />
</tr><br />
</table><br />
<br />
===Addresses===<br />
<br />
Addresses are further subdivided so that they can be presented linearly, in &quot;label&quot; form or as a VCARD etc, by combining the elements with suitable punctuation and markup, and also cross-linked where appropriate - for example the <strong>street</strong>&nbsp;element could be linked with the URL <strong><nowiki>http://www.cam.ac.uk/</nowiki><em>streetname</em></strong> to jump to the map for the street name. These should be used in order when presenting an address.<br />
<br />
Addresses may also be associated with geographical locations (sites, colleges and buildings) and their entrances. This supersedes the amorphous list of locations and entrances provided in version 5. An address may be<br />
<ul><br />
<li>just a postal address for correspondence, in which no location or entrances will be included in the address data</li><br />
<li>a postal address with a corresponding location on the ground (possibly with entrances)</li><br />
<li>just a location (and possibly its entrances), where the intention is to show the location on a map, but to direct post to a central address in a second address element, or occasionally that a postal address is not available for the location.</li><br />
</ul><br />
<br />
Each element contains a <strong>type</strong> field whose value is one of the keys in the following table, and then a key/value pair according to the type, as follows:<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
maildrop</td><br />
<td><br />
string</td><br />
<td><br />
for parts of an address such as a room number or a PO Box number</td><br />
</tr><br />
<tr><br />
<td><br />
building</td><br />
<td><br />
string</td><br />
<td><br />
name of building</td><br />
</tr><br />
<tr><br />
<td><br />
number</td><br />
<td><br />
string</td><br />
<td><br />
location on a street, e.g. &quot;42a&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
site</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;Lords Bridge&quot;, &quot;New Museums Site&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
street</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;Downing Place&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
street2</td><br />
<td><br />
string</td><br />
<td><br />
occasionally a second street is part of the address</td><br />
</tr><br />
<tr><br />
<td><br />
smallplace</td><br />
<td><br />
string</td><br />
<td><br />
where place is a local village</td><br />
</tr><br />
<tr><br />
<td><br />
place</td><br />
<td><br />
string</td><br />
<td><br />
usually &quot;Cambridge&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
county</td><br />
<td><br />
string</td><br />
<td><br />
rarely needed</td><br />
</tr><br />
<tr><br />
<td><br />
postcode</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
location</td><br />
<td><br />
location object</td><br />
<td><br />
see [[#Fields_common_to_all_geographical_objects|above]]. This is an excerpted geographical location object. There will only be at most one location object per address.</td><br />
</tr><br />
<tr><br />
<td><br />
entrance</td><br />
<td><br />
entrance object</td><br />
<td><br />
see [[#entrance|above]]. This is an excerpted geographical entrance object. There may be multiple entrance elements per address, but there will never be an entrance object in an address if there is no location object preceding it for the same address. Conversely, location elements do not have any entrance elements preceding them.</td><br />
</tr><br />
</table><br />
<br />
Some examples:<br />
<ul><br />
<li><br />
Hamilton Kerr Institute:<br /><br />
[ {&quot;type&quot;: &quot;street&quot;, &quot;street&quot;: &quot;Mill Lane&quot;},<br/>&nbsp;{&quot;type&quot;: &quot;smallplace&quot;, &quot;smallplace&quot;: &quot;Whittlesford&quot;},<br/>&nbsp;{&quot;type&quot;: &quot;place&quot;, &quot;place&quot;: &quot;Cambridge&quot;},<br/>&nbsp;{&quot;type&quot;: &quot;postcode&quot;, &quot;postcode&quot;: &quot;CB22 4NE&quot;}&nbsp;]</li><br />
<li><br />
Division of Anaesthesia<br /><br />
[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"maildrop",&nbsp;"maildrop":&nbsp;"Box&nbsp;93"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"maildrop",&nbsp;"maildrop":&nbsp;"Level&nbsp;4"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"site",&nbsp;"site":&nbsp;"Addenbrooke's&nbsp;Hospital"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"street",&nbsp;"street":&nbsp;"Hills&nbsp;Road"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"place",&nbsp;"place":&nbsp;"Cambridge"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"postcode",&nbsp;"postcode":&nbsp;"CB2&nbsp;2QQ"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"location",&nbsp;"location":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"building",&nbsp;"ref":&nbsp;"H132",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.17525,&nbsp;"lon":&nbsp;0.141464,&nbsp;"id":&nbsp;1643255315&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"H131-A",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"Addenbrooke's&nbsp;Hospital&nbsp;Main&nbsp;Entrance",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.175206,&nbsp;"lon":&nbsp;0.140538,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"direction":&nbsp;104,&nbsp;"user":&nbsp;"f",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;1643254795,&nbsp;<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;true&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance","ref":&nbsp;"H-A",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.176241,&nbsp;"lon":&nbsp;0.144354,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"direction":&nbsp;15,&nbsp;"user":&nbsp;"fbv",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;664530277,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;false<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;...<br/><br />
]</li><br />
</ul><br />
<br />
Here is a complete example record (for the Department of Anglo-Saxon, Norse and Celtic). Remember that all result records will be presented in an array, even if there is only one of them.<br />
<br />
&nbsp;&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"institution",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"inst":&nbsp;"asnc",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"prefix":&nbsp;"Department&nbsp;of",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"Anglo-Saxon,&nbsp;Norse&nbsp;and&nbsp;Celtic",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"sd":&nbsp;"asnc",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"role":&nbsp;"academic",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"info":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"address",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"address":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"number",&nbsp;"number":&nbsp;"9"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"street",&nbsp;"street":&nbsp;"West&nbsp;Road"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"place",&nbsp;"place":&nbsp;"Cambridge"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"postcode",&nbsp;"postcode":&nbsp;"CB3&nbsp;9DP"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"location",&nbsp;"location":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"building",&nbsp;"ref":&nbsp;"S040",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"Faculty&nbsp;of&nbsp;English",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.20246,&nbsp;"lon":&nbsp;0.108541,&nbsp;"id":&nbsp;26378099&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"S040-A",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.202422,&nbsp;"lon":&nbsp;0.108616,&nbsp;"direction":&nbsp;-169,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"user":&nbsp;"f",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;1487638771,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;true&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"S-C",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.202752,&nbsp;"lon":&nbsp;0.108839,&nbsp;"direction":&nbsp;94,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"user":&nbsp;"fb",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;961417125,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;false<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"S-E",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.202702,&nbsp;"lon":&nbsp;0.108056,&nbsp;"direction":&nbsp;94,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"user":&nbsp;"fbv",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;961417126,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;false&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;]<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"phone",&nbsp;"phone":&nbsp;"+44&nbsp;1223&nbsp;335079"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"fax",&nbsp;"fax":&nbsp;"+44&nbsp;1223&nbsp;335092"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"email",&nbsp;"email":&nbsp;"asnc@hermes.cam.ac.uk"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"url",&nbsp;"url":&nbsp;"http:\/\/www.asnc.cam.ac.uk\/"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"url",&nbsp;"url":&nbsp;"http:\/\/www.asnc.cam.ac.uk\/people\/index.htm",&nbsp;"role":&nbsp;"Contacts"&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;]<br/><br />
&nbsp;&nbsp;}<br/><br />
<br />
==Coordinates==<br />
<br />
There are very few real-world coordinates in the database (it doesn't, for example, include building outlines). But this information is available from the [http://wiki.openstreetmap.org/wiki/API OSM API] by reference to the OSM id in the 'id' field of all geographic entities.<br />
<br />
For building outlines, the OSM API supports:<br />
<br />
<nowiki>http://osm.org/api/0.6/way/<ID></nowiki><br />
<nowiki>http://osm.org/api/0.6/way/<ID>/full</nowiki><br />
<nowiki>http://osm.org/api/0.6/way/<ID>/relations</nowiki><br />
<br />
Note however that a building doesn't have to be just a single closed way, since it can have have holes in the area. These are handled as OSM "[http://wiki.openstreetmap.org/wiki/Relation:multipolygon multipolygons]". In essence, there is an outer way plus a number of inner ways <br />
<br />
For example, Churchill West Court (ref CHU016, https://map.cam.ac.uk/v6.json?ref=CHU016&debug=1). The Map API tells you it is a way with id 148247888 and you can plug it into the OSM API thus<br />
<br />
http://www.openstreetmap.org/api/0.6/way/148247888/full<br />
<br />
returning<br />
<br />
<pre><nowiki><br />
<osm version="0.6" generator="OpenStreetMap server"><br />
<node id="1613469175" lat="52.2128314" lon="0.1013427" version="1" changeset="10553242" user="davidearl" uid="3582" visible="true" timestamp="2012-01-31T20:37:02Z"/><br />
<node id="1613469065" lat="52.2127198" lon="0.101803" version="1" changeset="10553242" user="davidearl" uid="3582" visible="true" timestamp="2012-01-31T20:36:58Z"/><br />
...<br />
<nd ref="1613469175"/><br />
<nd ref="1613469065"/><br />
...<br />
<tag k="amenity" v="university"/><br />
<tag k="building" v="yes"/><br />
<tag k="name" v="West Court"/><br />
<tag k="operator" v="Churchill College (University of Cambridge)"/><br />
<tag k="ref" v="CHU016"/><br />
</way><br />
</osm><br />
</nowiki></pre><br />
<br />
and http://www.openstreetmap.org/api/0.6/way/148247888/relations gets<br />
<br />
<pre><nowiki><br />
<osm version="0.6" generator="OpenStreetMap server"><br />
<relation id="1999559" visible="true" timestamp="2012-01-31T20:40:32Z" version="1" changeset="10553242" user="davidearl" uid="3582"><br />
<member type="way" ref="148247888" role="outer"/><br />
<member type="way" ref="148248147" role="inner"/><br />
<tag k="type" v="multipolygon"/><br />
</relation><br />
</osm><br />
</nowiki></pre><br />
<br />
telling you it is a multipolygon outer, and giving the info to traverse to the inner as above.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Terms_and_conditions,_Copyright,_Fair_Use,_etc.&diff=742
Terms and conditions, Copyright, Fair Use, etc.
2017-10-20T22:47:51Z
<p>dje39: /* Using the tiles and map images */</p>
<hr />
<div>Our implementation of the map is provided to support the work of the University and its associated institutions. You are welcome to use it and its associated services (the [[Map Annotation | interactive]] and [[Map Annotation | programmatic]] annotation tools, the [[The Embedding API | embedding]], [[The Tile API | tile]], and [[The Database API | database]] APIs) and any derived or printed copies, for this purpose in any way that that is compatible with [http://www.admin.cam.ac.uk/univ/mission.html the mission of the University] to contribute to society through the pursuit of education, learning, and research at the highest international levels of excellence. If you are not clear if you proposed use is consistent with this then please ask (contact [mailto:service-desk@ucs.cam.ac.uk service-desk@ucs.cam.ac.uk]).<br />
<br />
There are however some things that you must or must not do and they are covered below.<br />
<br />
==Fair Use==<br />
<br />
We provide the on-line map and its associated services (annotation tools, embedding, tile, and database APIs) for others to use and in the hope that they will be useful. However placing an excessive load on the map infrastructure will degrade performance for all map users. Please try to keep the load you place on the map infrastructure to a minimum, for example by reducing the number of tiles that you load in one go or by appropriately caching results rather than always repeating requests. If you believe that you have an application that will cause, or is causing, problems to our infrastructure then please contact us at [mailto:service-desk@ucs.cam.ac.uk service-desk@ucs.cam.ac.uk] to discuss your needs.<br />
<br />
==The annotation service==<br />
<br />
Permission is granted to use the various aspects of the annotation service in accordance with the published instructions and specifications. The annotation service is open to various forms of abuse and everyone is expected to exercise care when using it. Using it to bring the University or any other organisation into disrepute, to publicise otherwise confidential information, or to compromise the privacy of individuals is expressly prohibited. In the event of misuse, individual annotations may be suppressed and some or all of the annotation features may be withdrawn.<br />
<br />
==Using the tiles and map images==<br />
<br />
The images and resulting tiles that make up the map are generated from information provided by [http://www.openstreetmap.org/ OpenStreetMap]. The [http://www.openstreetmap.org/copyright OpenStreetMap licence] (ODbL1.0) allows for this data to be reused in this way, but requires that OpenStreetMap is credited and that it is made clear that the maps are available under OSM's licence terms. See [http://www.openstreetmap.org/copyright the OSM copyright page] for guidance on how to achieve this. The default map, on it's own page or when included in an <iframe>, includes a suitable OpenStreetMap credit. This issue mainly applies to anyone using the Tile API or printable versions of the map.<br />
<br />
Map tiles and print maps are also copyright &copy; University of Cambridge. If you use our tiles or map images then as well as crediting OpenStreetMap please also credit the University of Cambridge and University Information Services for providing them. This is in your interest, because it will help to ensure that resources continue to be available to support the map system. <br />
<br />
We suggest "Base map data copyright &copy; OpenStreetMap contributors. Map tiles from the University of Cambridge Official Map, provided and managed by University Information Services". Where appropriate, please link 'University of Cambridge Official Map' to https://map.cam.ac.uk/ and 'University Information Services' to http://www.uis.cam.ac.uk/. Replace 'Map tiles' with 'Map images' for print maps.<br />
<br />
==Using the Database API==<br />
<br />
The contents of the institution index database are copyright © 2012 University of Cambridge. Permission is granted for reasonable use of this data via the published APIs as described above. Please credit this use "University data copyright University of Cambridge, used with permission. Data provided and managed by the University Computing Service". Where possible, please link 'University of Cambridge' to http://www.cam.ac.uk/ and 'University Computing Service' to http://www.ucs.cam.ac.uk/.<br />
<br />
The contents of the map database are copyright © OpenStreetMap contributors and licensed under the ODbL v1.0 license. See [http://www.openstreetmap.org/copyright OpenStreetMap] for more details.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Database_API&diff=741
The Database API
2017-10-20T22:46:24Z
<p>dje39: /* Coordinates */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use this API.<br />
<br />
This page describes version 6 of the API, made live on February 20, 2013.<br />
<br />
Version 5 ([[The_Database_API_v5|old documentation]]) has been withdrawn. You can see a [[The_Database_API_v6_changes|summary of changes from version 5]].<br />
<br />
There is an experimental [[Python Database API interface]] if you want to work with this API from Python.<br />
<br />
==Introduction==<br />
<br />
The same information as provided by the [[The Map URL API]] is provided in machine readable form using URLs like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>q=''search''[&amp;partial=yes]<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>bb=''boundingbox''<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>ref=''ref''<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>inst=''inst''<br />
<br />
with the same interpretation as in [[The Map URL API]] (note that one=list is not relevant in the q= and bb= variants, and the simple&nbsp;<em>name </em>variant is not available to the API - just use <strong><nowiki>http://map.cam.ac.uk/v6.json?</nowiki>q=<em>name</em></strong>).<br />
<p><br />
An additional option <strong>?limit=<em>limit</em></strong> is also available on the ?q and ?bb forms which limits the number of results returned to the number given. For example</p><br />
<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>q=saint&amp;limit=15<br />
<br />
Values of query parameters, such as <strong>?q=</strong> are limited to 2,000 characters. For <strong>?inst=</strong> and <strong>?ref=</strong> queries, a maximum of 25 may be requested at once (separating the requested codes with '|').<br />
<br />
<p>Also, there is another query type available to the database API not available when using a consumer URL. <strong>?alpha=<em>letter</em></strong> will provide an alphabetically ordered listing of the entire institution database for that letter. This is used as the basis for the directory page and other alphabetic listings. Please cache the results of this search so that it does not place an unwarranted load on the database. You can also filter by type, for example:</p><br />
<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>alpha=s&amp;filter=college<br />
<br />
<p>The version 6 API also supports discovery and navigation around the reference hierarchy. See [[The Database API reference discovery]] for more details. In addition, the [https://map.cam.ac.uk/refbrowser/ interactive browser] (also linked from the 'More...' menu) can be useful when exploring the data available and when identifying the various codes used.</p><br />
<br />
<p><br />
The &#39;v6&#39; is a version number, allowing for potential backward compatibility if we change the spec at some point in the future. Only v6 is useful for now. v5 was deprecated in January 2013 and backward compatibility was not provided.</p><br />
<p><br />
The &#39;json&#39; part indicates the results are provided in JSON format. We may produce other formats in future, in which case URLs such as&nbsp;<strong><nowiki>https://map.cam.ac.uk/v6.xml?</nowiki>...</strong> would be introduced, but for the time being, only JSON is supported.</p><br />
<p><br />
The result is a JSON array:</p><br />
<p style="margin-left: 40px; "><br />
[ { &quot;type&quot;: <em>type0</em>, ... }, { &quot;type&quot;:&nbsp;<em>type1</em>, ...<em>&nbsp;</em>}, ... ]</p><br />
<p><br />
where each object in the array is an entity matching the request.&nbsp;If there are <strong>no results</strong>, an empty array is produced. If there is <strong>only one result</strong>, it is still provided as an array (of one object), not as just the object. Note also that requests by inst and ref may occasionally also yield more than one result. </p><br />
<p><br />
The content of the rest of each object depends on:</p><br />
<ul><br />
<li><br />
<em>type</em></li><br />
<li><br />
what information is available for each result</li><br />
<li><br />
whether the request was a search (q=... or <em>name</em>) or direct look up (ref or inst URLs)</li><br />
</ul><br />
<p><br />
<i>type</i>&nbsp;is one of:</p><br />
<p style="margin-left: 40px; "><br />
<strong>error<br /><br />
institution<br /><br />
site<br /><br />
college</strong><br /><br />
<strong>building<br /><br />
entrance</strong><br /><br />
<strong>nonuniversity</strong><br /><br />
<strong>virtualsite</strong><br /><br />
<strong>street</strong><br /><br />
<strong>more</strong></p><br />
<br />
==Error reports==<br />
<br />
<p><br />
If <em>type</em> is <strong>error</strong>, then the http request will also return an appropriate status code, typically 400 indicating the request is malformed (wrong combination of query parameters, for example) or 404 (api version or format not implemented for example). The consumer should also be prepared to handle other HTTP errors generated by the server which will not provide JSON data (500 for example). Apart from these, all correctly formed requests will generate status 200. Note that this includes requests with no results (which produce an empty array).</p><br />
<p><br />
Note also that if you mis-spell &#39;v6.json&#39; (for example, say you incorrectly use a capital V), then the URL may be interpreted as the end-user form M:/<em>name</em> so you would get a stream of HTML!</p><br />
<br />
<p>v5.json, the now deprecated API, will always produce an error like this (actually an HTTP 410 error).</p><br />
<br />
==Entity structure==<br />
<p><br />
Contents of JSON objects representing entities found are as follows, by type.</p><br />
<br />
<p>In general, each request includes information about things linked to each result: the buildings for an institution, the entrances to a site and so on. This referencing only applies one level deep: those parts are excerpted: they do not themselves contain further entities to which they refer. If you need these, you would have to request the content by ref or inst from the parent. The fields omitted in the second level are indicated with an asterisk in the tables that follow.<br />
<br />
===error===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>error</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
code</td><br />
<td><br />
the HTTP status code</td><br />
<td><br />
int</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
error</td><br />
<td><br />
text describing the error</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===more===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>more</strong></td><br />
<td><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><br />
<td><br />
When the number of results is limited by <strong>?limit=<em>limit</em></strong>, the last element in the array of results may indicate "more", that there are more results that could be found but the limit was reached. Because certain results are redacted in some circumstances, note that the number of elements in the array may be fewer than limit+1 even if the limit is reached. "more" is not included if all the available results are returned. There isn't any way to page through the results: the search needs to be made more specific.</td><br />
</tr><br />
</table><br />
<br />
===institution===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>institution</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
inst</td><br />
<td><br />
the institution code of the entity</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
role</td><br />
<td><br />
kind of institution</td><br />
<td><br />
string, one of:<br /><br />
college<br /><br />
academic<br /><br />
admin<br /><br />
nonacademic<br /><br />
mrc<br /><br />
library<br /><br />
museum<br /><br />
lecture</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
prefix</td><br />
<td><br />
the name prefix</td><br />
<td><br />
string</td><br />
<td><br />
for example, &#39;Department of&#39;, &#39;Centre for&#39;</td><br />
</tr><br />
<tr><br />
<td><br />
name</td><br />
<td><br />
the substantive part of the institution name</td><br />
<td><br />
string</td><br />
<td><br />
for example, &#39;Geography&#39;. This is the field to sort on for alphabetically ordered institutions</td><br />
</tr><br />
<tr><br />
<td><br />
suffix</td><br />
<td><br />
the name suffix</td><br />
<td><br />
string</td><br />
<td><br />
often an acronym or former name, which would often be presented in parentheses. For example, when name is &#39;Advanced Photonics and Electronics&#39;, prefix is &#39;Centre for &#39; and&nbsp;suffix would be &#39;CAPE&#39;. The whole might be presented as &#39;Advanced Photonics and Electronics (CAPE), Centre for&#39; or &#39;Centre for Advanced Photonics and Electronics (CAPE)&#39;</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
when the entity is subsidiary to another, this is the institution code of the parent institution</td><br />
<td><br />
entity</td><br />
<td><br />
for example the faculty of a department</td><br />
</tr><br />
<tr><br />
<td><br />
options</td><br />
<td><br />
arbitrary space separated tokens indicating arbitrary options</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
sd</td><br />
<td><br />
the subdomain of the entity</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;lucy-cav&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
info</td><br />
<td><br />
contact information (etc)</td><br />
<td><br />
array of objects (see below)</td><br />
<td><br />
<p><br />
for example:</p><br />
<p><br />
&nbsp;&nbsp;"info":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"founded",&nbsp;"founded":&nbsp;"1505"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"address",&nbsp;"address":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"street",&nbsp;"street":&nbsp;"St&nbsp;Andrew's&nbsp;Street"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"place",&nbsp;"place":&nbsp;"Cambridge"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"postcode",&nbsp;"postcode":&nbsp;"CB2&nbsp;3BU"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{"type":&nbsp;"location",&nbsp;"location":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"college",&nbsp;"ref":&nbsp;"CHRISTS",&nbsp;"name":&nbsp;"Christ's&nbsp;College",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.206145,&nbsp;"lon":&nbsp;0.122944,&nbsp;"primitive":&nbsp;"w",&nbsp;"id":&nbsp;147488000<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br/><br />
&nbsp;&nbsp;]</p><br />
<br />
<p>Note that all this contact information relates to the entity concerned. Subordinate entities will have their own contact information if relevant.</p><br />
</td><br />
</tr><br />
<tr><br />
<td><br />
sortasvia</td><br />
<td><br />
when result matched via an AKA field (see below) or from a role, the index of the info element which it matched against</td><br />
<td><br />
integer</td><br />
<td><br />
<td></td><br />
</tr><br />
</table><br />
<br />
===virtualsite===<br />
<br />
'virtualsite' entities are '''''only''''' returned as part of [[The Database API reference discovery]] process in response to a search with 'ref=*' or 'ref=''SITE''/*'. These are just like sites and subsites except that they have no location information associated with them. They exist only so that the complete set of prefix letters (including those for buildings not on any real site) is available as a starting point for reference discovery (see the documentation for details). Looking up their ref verbatim will yield no result.<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td>type</td><br />
<td><strong>virtualsite</strong></td><br />
<td></td><br />
<td></td><br />
</tr><br />
<br />
<tr><br />
<td>ref</td><br />
<td>the reference of the entity</td><br />
<td>string</td><br />
<td>e.g. "K", "EXT/BEAUFORT"<br /><br />
See [[The Database API reference discovery]] for a discussion of reference formats</td><br />
</tr><br />
<br />
<tr><br />
<td>name</td><br />
<td>the name of the entity (assuming it has one)</td><br />
<td>string</td><br />
<td>"north city"</td><br />
</tr><br />
<tr><br />
<td>nonuniversity</td><br />
<td>key only present if the virtual site is not part of the university estate but where we want to refer to it in the map</td><br />
<td>boolean</td><br />
<td>always '''true''' if present. Currently the only virtual non-university site has reference 'EXT', along with some virtual sub-sites of 'EXT'</td><br />
</tr><br />
</table><br />
<br />
===Fields common to all geographical objects===<br />
<br />
The remainder are all geographical objects and share the following common fields:<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
ref</td><br />
<td><br />
the reference of the entity</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;H/FORVIE&quot;<br /><br />
See [[The Database API reference discovery]] for a discussion of reference formats,<br />
</td><br />
</tr><br />
<tr><br />
<td><br />
name</td><br />
<td><br />
the name of the entity (assuming it has one)</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;Forvie Site&quot;, &quot;Austin Building&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
lat</td><br />
<td><br />
the latitude of a representative position of the entity</td><br />
<td><br />
float</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
lon</td><br />
<td><br />
the longitude of a representative position of the entity</td><br />
<td><br />
float</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
primitive</td><br />
<td><br />
whether the building was derived from an OSM way (&quot;w&quot;) or node (&quot;n&quot;)</td><br />
<td><br />
string (either &quot;w&quot; or &quot;n&quot;)</td><br />
<td><br />
primitive and id can be used together to form a link to the OSM browser, as in http://osm.org/browse/way/1234567</td><br />
</tr><br />
<tr><br />
<td><br />
id</td><br />
<td><br />
the OSM id of the node or way from which the entity was derived</td><br />
<td><br />
int</td><br />
<td><br />
sites, colleges and buildings are usually areas (ways) in OSM, though there are a few "buildings" which represent an office in larger, possibly non-university premises, represented just as a node. Complex buildings, e.g. one containing 'holes', are represented as OSM 'multipologon relations'. In these cases the referenced way will be the one corresponding to the outside of the building - the holes can be accessed via the relation containing this way and OSM tags relating to the building will be associated with the outer way or the relation (but not both).<br/>&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===site===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>site</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
nonuniversity</td><br />
<td><br />
<strong>true</strong></td><br />
<td><br />
boolean</td><br />
<td><br />
present to distinguish non-university sites from university sites (currently the only non-virtual, non-university site is 'H', the Cambridge Biomedical Campus)</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
when the site is a sub-site, this is the main site</td><br />
<td><br />
site object</td><br />
<td><br />
for example object for &quot;Cambridge Biomedical Campus&quot; when name is &quot;Forvie Site&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
entrances*</td><br />
<td><br />
to the site</td><br />
<td><br />
array of entrance objects</td><br />
<td><br />
see below</td><br />
</tr><br />
</table><br />
<br />
===college===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>college</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
This is the geographical entity for a college site or sub-site, not the institutional information which is an inst. This is very similar to&nbsp;<strong>site</strong>.</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
when the college item is a subsidiary site, the main site</td><br />
<td><br />
college object</td><br />
<td><br />
e.g. object for &quot;Magdalene College&quot; when site is ref MAGD/CRIPPS</td><br />
</tr><br />
<tr><br />
<td><br />
entrances*</td><br />
<td><br />
as for site</td><br />
<td><br />
array of entrance objects</td><br />
<td><br />
see below</td><br />
</tr><br />
<tr><br />
<td><br />
institution*</td><br />
<td><br />
the institution information associated with this college area</td><br />
<td><br />
institution object</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===building===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>building</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
site/college in which the building is situated</td><br />
<td><br />
site/college object</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
entrances*</td><br />
<td><br />
entrances of the building</td><br />
<td><br />
array of entrance objects</td><br />
<td><br />
see below</td><br />
</tr><br />
<tr><br />
<td><br />
occupants*</td><br />
<td><br />
occupants of the building</td><br />
<td><br />
array of institution objects</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===entrance===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>entrance</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
entrances apply to sites and colleges as well as buildings. Note, entrances are always derived from OSM node entities.</td><br />
</tr><br />
<tr><br />
<td><br />
parents*</td><br />
<td><br />
buildings and/or sites/colleges to which this entrance gives access</td><br />
<td><br />
array of building/site/college objects</td><br />
<td><br />
note that a few entrances give access to university properties on either side; also occasionally an entrance to a building isn&#39;t actually part of the building footprint.</td><br />
</tr><br />
<tr><br />
<td><br />
occupants*</td><br />
<td><br />
the institutions that gain access by this entrance</td><br />
<td><br />
array of institution objects</td><br />
<td><br />
OK, you don&#39;t exactly &quot;occupy&quot; an entrance, but consistent with buildings</td><br />
</tr><br />
<tr><br />
<td><br />
direction</td><br />
<td><br />
the direction of a normal to the parent building/site/college at an entrance, in degrees between -180 and 180&nbsp;measured anticlockwise from the east (positive x axis) pointing away from the building</td><br />
<td><br />
float</td><br />
<td><br />
the direction can be used to orient an overlaid arrow pointing to the entrance.</td><br />
</tr><br />
<tr><br />
<td><br />
user</td><br />
<td><br />
some or all of the letters &quot;fbvg&quot;</td><br />
<td><br />
string</td><br />
<td><br />
standing for &quot;foot&quot;, &quot;bicycle&quot;, &quot;vehicle&quot; and &quot;goods&quot; respectively, indicating the class or classes of users which can use the entrance.</td><br />
</tr><br />
<tr><br />
<td><br />
door</td><br />
<td><br />
&nbsp;</td><br />
<td><br />
boolean</td><br />
<td><br />
whether this entrance is the door to a building (true) or a gate to a site (false)</td><br />
</tr><br />
</table><br />
<br />
===nonuniversity===<br />
<br />
Non-university objects are only provided no reference is available. Where they have a University reference they are included in the general scheme of sites and buildings, with the '''nonuniversity''' element set to '''true'''.<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<b>nonuniversity</b></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
role</td><br />
<td><br />
what kind of thing this is</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;hotel&quot;</td><br />
</tr><br />
</table><br />
<br />
===street===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<b>street</b></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
no additional fields other than the common ones</td><br />
</tr><br />
</table><br />
<br />
==Contact information==<br />
<br />
Contact information for institutions and colleges is grouped into an array of items each of which may be repeated and qualified as necessary. For example, multiple phone numbers with descriptions of what each is for.&nbsp;Note that these all relate to the entity concerned. Subordinate entities will have their own contact information if relevant, so addresses, phone numbers etc. for child institutions should not be given as alternate addresses within the same info array.<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
person</td><br />
<td><br />
string</td><br />
<td><br />
primary contact named individual, for example &quot;Prof. John Doe&quot;.</td><br />
</tr><br />
<tr><br />
<td><br />
description</td><br />
<td><br />
string</td><br />
<td><br />
A brief description of the function of the institution</td><br />
</tr><br />
<tr><br />
<td><br />
title</td><br />
<td><br />
string</td><br />
<td><br />
primary contact title, for example &quot;The Bursar&quot;, where useful for more personal addressing.</td><br />
</tr><br />
<tr><br />
<td><br />
address</td><br />
<td><br />
array of objects (see below)</td><br />
<td><br />
<p><br />
postal address (assumed to be the primary address if not described otherwise by the role attribute - see below).</p><br />
</td><br />
</tr><br />
<tr><br />
<td><br />
phone</td><br />
<td><br />
string</td><br />
<td><br />
in the international form +44 1223 33nnnn</td><br />
</tr><br />
<tr><br />
<td><br />
fax</td><br />
<td><br />
string</td><br />
<td><br />
ditto</td><br />
</tr><br />
<tr><br />
<td><br />
email</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
url</td><br />
<td><br />
string</td><br />
<td><br />
complete, including the http://</td><br />
</tr><br />
<tr><br />
<td><br />
founded</td><br />
<td><br />
int</td><br />
<td><br />
(colleges only) year of foundation</td><br />
</tr><br />
<tr><br />
<td><br />
logo</td><br />
<td><br />
string</td><br />
<td><br />
url of image which is used to brand the institution</td><br />
</tr><br />
<tr><br />
<td><br />
twitter</td><br />
<td><br />
string</td><br />
<td><br />
twitter handle including the @, e.g. @camgeog</td><br />
</tr><br />
<tr><br />
<td><br />
facebook</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
AKA</td><br />
<td><br />
string</td><br />
<td><br />
another name or search term by which the institution is known. Unlike other info fields, the value of this info item is (usually) added to the search index.<br />
<br />
<p>This may be used in different ways according to the accompanying options. An "xm" option excludes the entry from the paper map (this might be a very old name, for example, which you want search results to hit, but not include in an up-to-date static map). "xw" excludes it from the web site searches and presentation, but includes it in the paper map and other alphabetic listings. "xd" excludes it from presentation (the user doesn't see it), but includes it in the index.</p><br />
<br />
<p>Additionally when a ?q returns a result via a match on an AKA, the top level structure contains 'viaaka', the index of the info element which it matched against. This is so that you can tell the user if you want to why their search matched when it doesn't appear to match the main entry name.</p></td><br />
</tr><br />
<tr><br />
<td><br />
subsection</td><br />
<td><br />
string</td><br />
<td><br />
indicates that all the entries that follow up to a subsection-end entry or another subsection entry or the end of the info array are grouped together. This would typically be used where an institution lists contact details for a well-defined part or function of the institution - for example, the phone, fax and email for the Box Office part of the ADC Theatre. A consumer would typically render the subsection string as a subheading of some kind and possibly indent its contents or separate them out in some suitable way. (note: this supersedes the version 5 method of grouping, where repeated roles indicated subsections, which was rather clumsy and prevented the individual elements having their own roles).</td><br />
</tr><br />
<tr><br />
<td><br />
subsection-end</td><br />
<td><br />
string (unused)</td><br />
<td><br />
explicitly terminates a group of subsection elements.</td><br />
</tr><br />
</table><br />
<br />
===Contact information qualifiers===<br />
<br />
Each of these objects contains a type to identify the key, and may also contain other qualifying information, as follows:<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
one of the keys listed in the previous table</td><br />
<td><br />
</td><br />
</tr><br />
<tr><br />
<td><br />
role</td><br />
<td><br />
string</td><br />
<td><br />
description of what the contact information will be used for. If omitted, assumed to be the primary contact information of this type. For URLs this would typically be used for the link text rather than displaying the URL itself. For others it would serve as a caption.&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
options</td><br />
<td><br />
string</td><br />
<td><br />
arbitrary space separated string of options (meanings client dependent)</td><br />
</tr><br />
</table><br />
<br />
===Addresses===<br />
<br />
Addresses are further subdivided so that they can be presented linearly, in &quot;label&quot; form or as a VCARD etc, by combining the elements with suitable punctuation and markup, and also cross-linked where appropriate - for example the <strong>street</strong>&nbsp;element could be linked with the URL <strong><nowiki>http://www.cam.ac.uk/</nowiki><em>streetname</em></strong> to jump to the map for the street name. These should be used in order when presenting an address.<br />
<br />
Addresses may also be associated with geographical locations (sites, colleges and buildings) and their entrances. This supersedes the amorphous list of locations and entrances provided in version 5. An address may be<br />
<ul><br />
<li>just a postal address for correspondence, in which no location or entrances will be included in the address data</li><br />
<li>a postal address with a corresponding location on the ground (possibly with entrances)</li><br />
<li>just a location (and possibly its entrances), where the intention is to show the location on a map, but to direct post to a central address in a second address element, or occasionally that a postal address is not available for the location.</li><br />
</ul><br />
<br />
Each element contains a <strong>type</strong> field whose value is one of the keys in the following table, and then a key/value pair according to the type, as follows:<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
maildrop</td><br />
<td><br />
string</td><br />
<td><br />
for parts of an address such as a room number or a PO Box number</td><br />
</tr><br />
<tr><br />
<td><br />
building</td><br />
<td><br />
string</td><br />
<td><br />
name of building</td><br />
</tr><br />
<tr><br />
<td><br />
number</td><br />
<td><br />
string</td><br />
<td><br />
location on a street, e.g. &quot;42a&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
site</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;Lords Bridge&quot;, &quot;New Museums Site&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
street</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;Downing Place&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
street2</td><br />
<td><br />
string</td><br />
<td><br />
occasionally a second street is part of the address</td><br />
</tr><br />
<tr><br />
<td><br />
smallplace</td><br />
<td><br />
string</td><br />
<td><br />
where place is a local village</td><br />
</tr><br />
<tr><br />
<td><br />
place</td><br />
<td><br />
string</td><br />
<td><br />
usually &quot;Cambridge&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
county</td><br />
<td><br />
string</td><br />
<td><br />
rarely needed</td><br />
</tr><br />
<tr><br />
<td><br />
postcode</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
location</td><br />
<td><br />
location object</td><br />
<td><br />
see [[#Fields_common_to_all_geographical_objects|above]]. This is an excerpted geographical location object. There will only be at most one location object per address.</td><br />
</tr><br />
<tr><br />
<td><br />
entrance</td><br />
<td><br />
entrance object</td><br />
<td><br />
see [[#entrance|above]]. This is an excerpted geographical entrance object. There may be multiple entrance elements per address, but there will never be an entrance object in an address if there is no location object preceding it for the same address. Conversely, location elements do not have any entrance elements preceding them.</td><br />
</tr><br />
</table><br />
<br />
Some examples:<br />
<ul><br />
<li><br />
Hamilton Kerr Institute:<br /><br />
[ {&quot;type&quot;: &quot;street&quot;, &quot;street&quot;: &quot;Mill Lane&quot;},<br/>&nbsp;{&quot;type&quot;: &quot;smallplace&quot;, &quot;smallplace&quot;: &quot;Whittlesford&quot;},<br/>&nbsp;{&quot;type&quot;: &quot;place&quot;, &quot;place&quot;: &quot;Cambridge&quot;},<br/>&nbsp;{&quot;type&quot;: &quot;postcode&quot;, &quot;postcode&quot;: &quot;CB22 4NE&quot;}&nbsp;]</li><br />
<li><br />
Division of Anaesthesia<br /><br />
[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"maildrop",&nbsp;"maildrop":&nbsp;"Box&nbsp;93"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"maildrop",&nbsp;"maildrop":&nbsp;"Level&nbsp;4"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"site",&nbsp;"site":&nbsp;"Addenbrooke's&nbsp;Hospital"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"street",&nbsp;"street":&nbsp;"Hills&nbsp;Road"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"place",&nbsp;"place":&nbsp;"Cambridge"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"postcode",&nbsp;"postcode":&nbsp;"CB2&nbsp;2QQ"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"location",&nbsp;"location":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"building",&nbsp;"ref":&nbsp;"H132",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.17525,&nbsp;"lon":&nbsp;0.141464,&nbsp;"id":&nbsp;1643255315&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"H131-A",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"Addenbrooke's&nbsp;Hospital&nbsp;Main&nbsp;Entrance",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.175206,&nbsp;"lon":&nbsp;0.140538,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"direction":&nbsp;104,&nbsp;"user":&nbsp;"f",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;1643254795,&nbsp;<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;true&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance","ref":&nbsp;"H-A",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.176241,&nbsp;"lon":&nbsp;0.144354,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"direction":&nbsp;15,&nbsp;"user":&nbsp;"fbv",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;664530277,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;false<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;...<br/><br />
]</li><br />
</ul><br />
<br />
Here is a complete example record (for the Department of Anglo-Saxon, Norse and Celtic). Remember that all result records will be presented in an array, even if there is only one of them.<br />
<br />
&nbsp;&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"institution",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"inst":&nbsp;"asnc",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"prefix":&nbsp;"Department&nbsp;of",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"Anglo-Saxon,&nbsp;Norse&nbsp;and&nbsp;Celtic",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"sd":&nbsp;"asnc",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"role":&nbsp;"academic",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"info":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"address",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"address":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"number",&nbsp;"number":&nbsp;"9"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"street",&nbsp;"street":&nbsp;"West&nbsp;Road"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"place",&nbsp;"place":&nbsp;"Cambridge"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"postcode",&nbsp;"postcode":&nbsp;"CB3&nbsp;9DP"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"location",&nbsp;"location":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"building",&nbsp;"ref":&nbsp;"S040",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"Faculty&nbsp;of&nbsp;English",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.20246,&nbsp;"lon":&nbsp;0.108541,&nbsp;"id":&nbsp;26378099&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"S040-A",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.202422,&nbsp;"lon":&nbsp;0.108616,&nbsp;"direction":&nbsp;-169,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"user":&nbsp;"f",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;1487638771,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;true&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"S-C",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.202752,&nbsp;"lon":&nbsp;0.108839,&nbsp;"direction":&nbsp;94,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"user":&nbsp;"fb",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;961417125,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;false<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"S-E",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.202702,&nbsp;"lon":&nbsp;0.108056,&nbsp;"direction":&nbsp;94,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"user":&nbsp;"fbv",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;961417126,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;false&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;]<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"phone",&nbsp;"phone":&nbsp;"+44&nbsp;1223&nbsp;335079"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"fax",&nbsp;"fax":&nbsp;"+44&nbsp;1223&nbsp;335092"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"email",&nbsp;"email":&nbsp;"asnc@hermes.cam.ac.uk"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"url",&nbsp;"url":&nbsp;"http:\/\/www.asnc.cam.ac.uk\/"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"url",&nbsp;"url":&nbsp;"http:\/\/www.asnc.cam.ac.uk\/people\/index.htm",&nbsp;"role":&nbsp;"Contacts"&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;]<br/><br />
&nbsp;&nbsp;}<br/><br />
<br />
==Coordinates==<br />
<br />
There are very few real-world coordinates in the database (it doesn't, for example, include building outlines). But this information is available from the [http://wiki.openstreetmap.org/wiki/API OSM API] by reference to the OSM id in the 'id' field of all geographic entities.<br />
<br />
For building outlines, the OSM API supports:<br />
<br />
<nowiki>http://osm.org/api/0.6/way/<ID></nowiki><br />
<nowiki>http://osm.org/api/0.6/way/<ID>/full</nowiki><br />
<nowiki>http://osm.org/api/0.6/way/<ID>/relations</nowiki><br />
<br />
Note however that a building doesn't have to be just a single closed way, since it can have have holes in the area. These are handled as OSM "[http://wiki.openstreetmap.org/wiki/Relation:multipolygon multipolygons]". In essence, there is an outer way plus a number of inner ways <br />
<br />
For example, Churchill West Court (ref CHU016, https://map.cam.ac.uk/v6.json?ref=CHU016&debug=1). The Map API tells you it is a way with id 148247888 and you can plug it into the OSM API thus<br />
<br />
http://www.openstreetmap.org/api/0.6/way/148247888/full<br />
<br />
returning<br />
<br />
<pre><nowiki><br />
<osm version="0.6" generator="OpenStreetMap server"><br />
<node id="1613469175" lat="52.2128314" lon="0.1013427" version="1" changeset="10553242" user="davidearl" uid="3582" visible="true" timestamp="2012-01-31T20:37:02Z"/><br />
<node id="1613469065" lat="52.2127198" lon="0.101803" version="1" changeset="10553242" user="davidearl" uid="3582" visible="true" timestamp="2012-01-31T20:36:58Z"/><br />
...<br />
<nd ref="1613469175"/><br />
<nd ref="1613469065"/><br />
...<br />
<tag k="amenity" v="university"/><br />
<tag k="building" v="yes"/><br />
<tag k="name" v="West Court"/><br />
<tag k="operator" v="Churchill College (University of Cambridge)"/><br />
<tag k="ref" v="CHU016"/><br />
</way><br />
</osm><br />
</nowiki></pre><br />
<br />
and http://www.openstreetmap.org/api/0.6/way/148247888/relations gets<br />
<br />
<pre><nowiki><br />
<osm version="0.6" generator="OpenStreetMap server"><br />
<relation id="1999559" visible="true" timestamp="2012-01-31T20:40:32Z" version="1" changeset="10553242" user="davidearl" uid="3582"><br />
<member type="way" ref="148247888" role="outer"/><br />
<member type="way" ref="148248147" role="inner"/><br />
<tag k="type" v="multipolygon"/><br />
</relation><br />
</osm><br />
</nowiki></pre><br />
<br />
telling you it is a multipolygon outer, and giving the info to traverse to the inner as above.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Database_API&diff=740
The Database API
2017-10-20T22:45:35Z
<p>dje39: </p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use this API.<br />
<br />
This page describes version 6 of the API, made live on February 20, 2013.<br />
<br />
Version 5 ([[The_Database_API_v5|old documentation]]) has been withdrawn. You can see a [[The_Database_API_v6_changes|summary of changes from version 5]].<br />
<br />
There is an experimental [[Python Database API interface]] if you want to work with this API from Python.<br />
<br />
==Introduction==<br />
<br />
The same information as provided by the [[The Map URL API]] is provided in machine readable form using URLs like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>q=''search''[&amp;partial=yes]<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>bb=''boundingbox''<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>ref=''ref''<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>inst=''inst''<br />
<br />
with the same interpretation as in [[The Map URL API]] (note that one=list is not relevant in the q= and bb= variants, and the simple&nbsp;<em>name </em>variant is not available to the API - just use <strong><nowiki>http://map.cam.ac.uk/v6.json?</nowiki>q=<em>name</em></strong>).<br />
<p><br />
An additional option <strong>?limit=<em>limit</em></strong> is also available on the ?q and ?bb forms which limits the number of results returned to the number given. For example</p><br />
<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>q=saint&amp;limit=15<br />
<br />
Values of query parameters, such as <strong>?q=</strong> are limited to 2,000 characters. For <strong>?inst=</strong> and <strong>?ref=</strong> queries, a maximum of 25 may be requested at once (separating the requested codes with '|').<br />
<br />
<p>Also, there is another query type available to the database API not available when using a consumer URL. <strong>?alpha=<em>letter</em></strong> will provide an alphabetically ordered listing of the entire institution database for that letter. This is used as the basis for the directory page and other alphabetic listings. Please cache the results of this search so that it does not place an unwarranted load on the database. You can also filter by type, for example:</p><br />
<br />
<nowiki>https://map.cam.ac.uk/v6.json?</nowiki>alpha=s&amp;filter=college<br />
<br />
<p>The version 6 API also supports discovery and navigation around the reference hierarchy. See [[The Database API reference discovery]] for more details. In addition, the [https://map.cam.ac.uk/refbrowser/ interactive browser] (also linked from the 'More...' menu) can be useful when exploring the data available and when identifying the various codes used.</p><br />
<br />
<p><br />
The &#39;v6&#39; is a version number, allowing for potential backward compatibility if we change the spec at some point in the future. Only v6 is useful for now. v5 was deprecated in January 2013 and backward compatibility was not provided.</p><br />
<p><br />
The &#39;json&#39; part indicates the results are provided in JSON format. We may produce other formats in future, in which case URLs such as&nbsp;<strong><nowiki>https://map.cam.ac.uk/v6.xml?</nowiki>...</strong> would be introduced, but for the time being, only JSON is supported.</p><br />
<p><br />
The result is a JSON array:</p><br />
<p style="margin-left: 40px; "><br />
[ { &quot;type&quot;: <em>type0</em>, ... }, { &quot;type&quot;:&nbsp;<em>type1</em>, ...<em>&nbsp;</em>}, ... ]</p><br />
<p><br />
where each object in the array is an entity matching the request.&nbsp;If there are <strong>no results</strong>, an empty array is produced. If there is <strong>only one result</strong>, it is still provided as an array (of one object), not as just the object. Note also that requests by inst and ref may occasionally also yield more than one result. </p><br />
<p><br />
The content of the rest of each object depends on:</p><br />
<ul><br />
<li><br />
<em>type</em></li><br />
<li><br />
what information is available for each result</li><br />
<li><br />
whether the request was a search (q=... or <em>name</em>) or direct look up (ref or inst URLs)</li><br />
</ul><br />
<p><br />
<i>type</i>&nbsp;is one of:</p><br />
<p style="margin-left: 40px; "><br />
<strong>error<br /><br />
institution<br /><br />
site<br /><br />
college</strong><br /><br />
<strong>building<br /><br />
entrance</strong><br /><br />
<strong>nonuniversity</strong><br /><br />
<strong>virtualsite</strong><br /><br />
<strong>street</strong><br /><br />
<strong>more</strong></p><br />
<br />
==Error reports==<br />
<br />
<p><br />
If <em>type</em> is <strong>error</strong>, then the http request will also return an appropriate status code, typically 400 indicating the request is malformed (wrong combination of query parameters, for example) or 404 (api version or format not implemented for example). The consumer should also be prepared to handle other HTTP errors generated by the server which will not provide JSON data (500 for example). Apart from these, all correctly formed requests will generate status 200. Note that this includes requests with no results (which produce an empty array).</p><br />
<p><br />
Note also that if you mis-spell &#39;v6.json&#39; (for example, say you incorrectly use a capital V), then the URL may be interpreted as the end-user form M:/<em>name</em> so you would get a stream of HTML!</p><br />
<br />
<p>v5.json, the now deprecated API, will always produce an error like this (actually an HTTP 410 error).</p><br />
<br />
==Entity structure==<br />
<p><br />
Contents of JSON objects representing entities found are as follows, by type.</p><br />
<br />
<p>In general, each request includes information about things linked to each result: the buildings for an institution, the entrances to a site and so on. This referencing only applies one level deep: those parts are excerpted: they do not themselves contain further entities to which they refer. If you need these, you would have to request the content by ref or inst from the parent. The fields omitted in the second level are indicated with an asterisk in the tables that follow.<br />
<br />
===error===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>error</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
code</td><br />
<td><br />
the HTTP status code</td><br />
<td><br />
int</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
error</td><br />
<td><br />
text describing the error</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===more===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>more</strong></td><br />
<td><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><br />
<td><br />
When the number of results is limited by <strong>?limit=<em>limit</em></strong>, the last element in the array of results may indicate "more", that there are more results that could be found but the limit was reached. Because certain results are redacted in some circumstances, note that the number of elements in the array may be fewer than limit+1 even if the limit is reached. "more" is not included if all the available results are returned. There isn't any way to page through the results: the search needs to be made more specific.</td><br />
</tr><br />
</table><br />
<br />
===institution===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>institution</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
inst</td><br />
<td><br />
the institution code of the entity</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
role</td><br />
<td><br />
kind of institution</td><br />
<td><br />
string, one of:<br /><br />
college<br /><br />
academic<br /><br />
admin<br /><br />
nonacademic<br /><br />
mrc<br /><br />
library<br /><br />
museum<br /><br />
lecture</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
prefix</td><br />
<td><br />
the name prefix</td><br />
<td><br />
string</td><br />
<td><br />
for example, &#39;Department of&#39;, &#39;Centre for&#39;</td><br />
</tr><br />
<tr><br />
<td><br />
name</td><br />
<td><br />
the substantive part of the institution name</td><br />
<td><br />
string</td><br />
<td><br />
for example, &#39;Geography&#39;. This is the field to sort on for alphabetically ordered institutions</td><br />
</tr><br />
<tr><br />
<td><br />
suffix</td><br />
<td><br />
the name suffix</td><br />
<td><br />
string</td><br />
<td><br />
often an acronym or former name, which would often be presented in parentheses. For example, when name is &#39;Advanced Photonics and Electronics&#39;, prefix is &#39;Centre for &#39; and&nbsp;suffix would be &#39;CAPE&#39;. The whole might be presented as &#39;Advanced Photonics and Electronics (CAPE), Centre for&#39; or &#39;Centre for Advanced Photonics and Electronics (CAPE)&#39;</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
when the entity is subsidiary to another, this is the institution code of the parent institution</td><br />
<td><br />
entity</td><br />
<td><br />
for example the faculty of a department</td><br />
</tr><br />
<tr><br />
<td><br />
options</td><br />
<td><br />
arbitrary space separated tokens indicating arbitrary options</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
sd</td><br />
<td><br />
the subdomain of the entity</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;lucy-cav&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
info</td><br />
<td><br />
contact information (etc)</td><br />
<td><br />
array of objects (see below)</td><br />
<td><br />
<p><br />
for example:</p><br />
<p><br />
&nbsp;&nbsp;"info":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"founded",&nbsp;"founded":&nbsp;"1505"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"address",&nbsp;"address":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"street",&nbsp;"street":&nbsp;"St&nbsp;Andrew's&nbsp;Street"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"place",&nbsp;"place":&nbsp;"Cambridge"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"postcode",&nbsp;"postcode":&nbsp;"CB2&nbsp;3BU"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{"type":&nbsp;"location",&nbsp;"location":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"college",&nbsp;"ref":&nbsp;"CHRISTS",&nbsp;"name":&nbsp;"Christ's&nbsp;College",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.206145,&nbsp;"lon":&nbsp;0.122944,&nbsp;"primitive":&nbsp;"w",&nbsp;"id":&nbsp;147488000<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...<br/><br />
&nbsp;&nbsp;]</p><br />
<br />
<p>Note that all this contact information relates to the entity concerned. Subordinate entities will have their own contact information if relevant.</p><br />
</td><br />
</tr><br />
<tr><br />
<td><br />
sortasvia</td><br />
<td><br />
when result matched via an AKA field (see below) or from a role, the index of the info element which it matched against</td><br />
<td><br />
integer</td><br />
<td><br />
<td></td><br />
</tr><br />
</table><br />
<br />
===virtualsite===<br />
<br />
'virtualsite' entities are '''''only''''' returned as part of [[The Database API reference discovery]] process in response to a search with 'ref=*' or 'ref=''SITE''/*'. These are just like sites and subsites except that they have no location information associated with them. They exist only so that the complete set of prefix letters (including those for buildings not on any real site) is available as a starting point for reference discovery (see the documentation for details). Looking up their ref verbatim will yield no result.<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td>type</td><br />
<td><strong>virtualsite</strong></td><br />
<td></td><br />
<td></td><br />
</tr><br />
<br />
<tr><br />
<td>ref</td><br />
<td>the reference of the entity</td><br />
<td>string</td><br />
<td>e.g. "K", "EXT/BEAUFORT"<br /><br />
See [[The Database API reference discovery]] for a discussion of reference formats</td><br />
</tr><br />
<br />
<tr><br />
<td>name</td><br />
<td>the name of the entity (assuming it has one)</td><br />
<td>string</td><br />
<td>"north city"</td><br />
</tr><br />
<tr><br />
<td>nonuniversity</td><br />
<td>key only present if the virtual site is not part of the university estate but where we want to refer to it in the map</td><br />
<td>boolean</td><br />
<td>always '''true''' if present. Currently the only virtual non-university site has reference 'EXT', along with some virtual sub-sites of 'EXT'</td><br />
</tr><br />
</table><br />
<br />
===Fields common to all geographical objects===<br />
<br />
The remainder are all geographical objects and share the following common fields:<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
ref</td><br />
<td><br />
the reference of the entity</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;H/FORVIE&quot;<br /><br />
See [[The Database API reference discovery]] for a discussion of reference formats,<br />
</td><br />
</tr><br />
<tr><br />
<td><br />
name</td><br />
<td><br />
the name of the entity (assuming it has one)</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;Forvie Site&quot;, &quot;Austin Building&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
lat</td><br />
<td><br />
the latitude of a representative position of the entity</td><br />
<td><br />
float</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
lon</td><br />
<td><br />
the longitude of a representative position of the entity</td><br />
<td><br />
float</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
primitive</td><br />
<td><br />
whether the building was derived from an OSM way (&quot;w&quot;) or node (&quot;n&quot;)</td><br />
<td><br />
string (either &quot;w&quot; or &quot;n&quot;)</td><br />
<td><br />
primitive and id can be used together to form a link to the OSM browser, as in http://osm.org/browse/way/1234567</td><br />
</tr><br />
<tr><br />
<td><br />
id</td><br />
<td><br />
the OSM id of the node or way from which the entity was derived</td><br />
<td><br />
int</td><br />
<td><br />
sites, colleges and buildings are usually areas (ways) in OSM, though there are a few "buildings" which represent an office in larger, possibly non-university premises, represented just as a node. Complex buildings, e.g. one containing 'holes', are represented as OSM 'multipologon relations'. In these cases the referenced way will be the one corresponding to the outside of the building - the holes can be accessed via the relation containing this way and OSM tags relating to the building will be associated with the outer way or the relation (but not both).<br/>&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===site===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>site</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
nonuniversity</td><br />
<td><br />
<strong>true</strong></td><br />
<td><br />
boolean</td><br />
<td><br />
present to distinguish non-university sites from university sites (currently the only non-virtual, non-university site is 'H', the Cambridge Biomedical Campus)</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
when the site is a sub-site, this is the main site</td><br />
<td><br />
site object</td><br />
<td><br />
for example object for &quot;Cambridge Biomedical Campus&quot; when name is &quot;Forvie Site&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
entrances*</td><br />
<td><br />
to the site</td><br />
<td><br />
array of entrance objects</td><br />
<td><br />
see below</td><br />
</tr><br />
</table><br />
<br />
===college===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>college</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
This is the geographical entity for a college site or sub-site, not the institutional information which is an inst. This is very similar to&nbsp;<strong>site</strong>.</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
when the college item is a subsidiary site, the main site</td><br />
<td><br />
college object</td><br />
<td><br />
e.g. object for &quot;Magdalene College&quot; when site is ref MAGD/CRIPPS</td><br />
</tr><br />
<tr><br />
<td><br />
entrances*</td><br />
<td><br />
as for site</td><br />
<td><br />
array of entrance objects</td><br />
<td><br />
see below</td><br />
</tr><br />
<tr><br />
<td><br />
institution*</td><br />
<td><br />
the institution information associated with this college area</td><br />
<td><br />
institution object</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===building===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>building</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
parent*</td><br />
<td><br />
site/college in which the building is situated</td><br />
<td><br />
site/college object</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
entrances*</td><br />
<td><br />
entrances of the building</td><br />
<td><br />
array of entrance objects</td><br />
<td><br />
see below</td><br />
</tr><br />
<tr><br />
<td><br />
occupants*</td><br />
<td><br />
occupants of the building</td><br />
<td><br />
array of institution objects</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
</table><br />
<br />
===entrance===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<strong>entrance</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
entrances apply to sites and colleges as well as buildings. Note, entrances are always derived from OSM node entities.</td><br />
</tr><br />
<tr><br />
<td><br />
parents*</td><br />
<td><br />
buildings and/or sites/colleges to which this entrance gives access</td><br />
<td><br />
array of building/site/college objects</td><br />
<td><br />
note that a few entrances give access to university properties on either side; also occasionally an entrance to a building isn&#39;t actually part of the building footprint.</td><br />
</tr><br />
<tr><br />
<td><br />
occupants*</td><br />
<td><br />
the institutions that gain access by this entrance</td><br />
<td><br />
array of institution objects</td><br />
<td><br />
OK, you don&#39;t exactly &quot;occupy&quot; an entrance, but consistent with buildings</td><br />
</tr><br />
<tr><br />
<td><br />
direction</td><br />
<td><br />
the direction of a normal to the parent building/site/college at an entrance, in degrees between -180 and 180&nbsp;measured anticlockwise from the east (positive x axis) pointing away from the building</td><br />
<td><br />
float</td><br />
<td><br />
the direction can be used to orient an overlaid arrow pointing to the entrance.</td><br />
</tr><br />
<tr><br />
<td><br />
user</td><br />
<td><br />
some or all of the letters &quot;fbvg&quot;</td><br />
<td><br />
string</td><br />
<td><br />
standing for &quot;foot&quot;, &quot;bicycle&quot;, &quot;vehicle&quot; and &quot;goods&quot; respectively, indicating the class or classes of users which can use the entrance.</td><br />
</tr><br />
<tr><br />
<td><br />
door</td><br />
<td><br />
&nbsp;</td><br />
<td><br />
boolean</td><br />
<td><br />
whether this entrance is the door to a building (true) or a gate to a site (false)</td><br />
</tr><br />
</table><br />
<br />
===nonuniversity===<br />
<br />
Non-university objects are only provided no reference is available. Where they have a University reference they are included in the general scheme of sites and buildings, with the '''nonuniversity''' element set to '''true'''.<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<b>nonuniversity</b></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
role</td><br />
<td><br />
what kind of thing this is</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;hotel&quot;</td><br />
</tr><br />
</table><br />
<br />
===street===<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
<strong>notes</strong></td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
<b>street</b></td><br />
<td><br />
&nbsp;</td><br />
<td><br />
no additional fields other than the common ones</td><br />
</tr><br />
</table><br />
<br />
==Contact information==<br />
<br />
Contact information for institutions and colleges is grouped into an array of items each of which may be repeated and qualified as necessary. For example, multiple phone numbers with descriptions of what each is for.&nbsp;Note that these all relate to the entity concerned. Subordinate entities will have their own contact information if relevant, so addresses, phone numbers etc. for child institutions should not be given as alternate addresses within the same info array.<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
person</td><br />
<td><br />
string</td><br />
<td><br />
primary contact named individual, for example &quot;Prof. John Doe&quot;.</td><br />
</tr><br />
<tr><br />
<td><br />
description</td><br />
<td><br />
string</td><br />
<td><br />
A brief description of the function of the institution</td><br />
</tr><br />
<tr><br />
<td><br />
title</td><br />
<td><br />
string</td><br />
<td><br />
primary contact title, for example &quot;The Bursar&quot;, where useful for more personal addressing.</td><br />
</tr><br />
<tr><br />
<td><br />
address</td><br />
<td><br />
array of objects (see below)</td><br />
<td><br />
<p><br />
postal address (assumed to be the primary address if not described otherwise by the role attribute - see below).</p><br />
</td><br />
</tr><br />
<tr><br />
<td><br />
phone</td><br />
<td><br />
string</td><br />
<td><br />
in the international form +44 1223 33nnnn</td><br />
</tr><br />
<tr><br />
<td><br />
fax</td><br />
<td><br />
string</td><br />
<td><br />
ditto</td><br />
</tr><br />
<tr><br />
<td><br />
email</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
url</td><br />
<td><br />
string</td><br />
<td><br />
complete, including the http://</td><br />
</tr><br />
<tr><br />
<td><br />
founded</td><br />
<td><br />
int</td><br />
<td><br />
(colleges only) year of foundation</td><br />
</tr><br />
<tr><br />
<td><br />
logo</td><br />
<td><br />
string</td><br />
<td><br />
url of image which is used to brand the institution</td><br />
</tr><br />
<tr><br />
<td><br />
twitter</td><br />
<td><br />
string</td><br />
<td><br />
twitter handle including the @, e.g. @camgeog</td><br />
</tr><br />
<tr><br />
<td><br />
facebook</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
AKA</td><br />
<td><br />
string</td><br />
<td><br />
another name or search term by which the institution is known. Unlike other info fields, the value of this info item is (usually) added to the search index.<br />
<br />
<p>This may be used in different ways according to the accompanying options. An "xm" option excludes the entry from the paper map (this might be a very old name, for example, which you want search results to hit, but not include in an up-to-date static map). "xw" excludes it from the web site searches and presentation, but includes it in the paper map and other alphabetic listings. "xd" excludes it from presentation (the user doesn't see it), but includes it in the index.</p><br />
<br />
<p>Additionally when a ?q returns a result via a match on an AKA, the top level structure contains 'viaaka', the index of the info element which it matched against. This is so that you can tell the user if you want to why their search matched when it doesn't appear to match the main entry name.</p></td><br />
</tr><br />
<tr><br />
<td><br />
subsection</td><br />
<td><br />
string</td><br />
<td><br />
indicates that all the entries that follow up to a subsection-end entry or another subsection entry or the end of the info array are grouped together. This would typically be used where an institution lists contact details for a well-defined part or function of the institution - for example, the phone, fax and email for the Box Office part of the ADC Theatre. A consumer would typically render the subsection string as a subheading of some kind and possibly indent its contents or separate them out in some suitable way. (note: this supersedes the version 5 method of grouping, where repeated roles indicated subsections, which was rather clumsy and prevented the individual elements having their own roles).</td><br />
</tr><br />
<tr><br />
<td><br />
subsection-end</td><br />
<td><br />
string (unused)</td><br />
<td><br />
explicitly terminates a group of subsection elements.</td><br />
</tr><br />
</table><br />
<br />
===Contact information qualifiers===<br />
<br />
Each of these objects contains a type to identify the key, and may also contain other qualifying information, as follows:<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
type</td><br />
<td><br />
one of the keys listed in the previous table</td><br />
<td><br />
</td><br />
</tr><br />
<tr><br />
<td><br />
role</td><br />
<td><br />
string</td><br />
<td><br />
description of what the contact information will be used for. If omitted, assumed to be the primary contact information of this type. For URLs this would typically be used for the link text rather than displaying the URL itself. For others it would serve as a caption.&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
options</td><br />
<td><br />
string</td><br />
<td><br />
arbitrary space separated string of options (meanings client dependent)</td><br />
</tr><br />
</table><br />
<br />
===Addresses===<br />
<br />
Addresses are further subdivided so that they can be presented linearly, in &quot;label&quot; form or as a VCARD etc, by combining the elements with suitable punctuation and markup, and also cross-linked where appropriate - for example the <strong>street</strong>&nbsp;element could be linked with the URL <strong><nowiki>http://www.cam.ac.uk/</nowiki><em>streetname</em></strong> to jump to the map for the street name. These should be used in order when presenting an address.<br />
<br />
Addresses may also be associated with geographical locations (sites, colleges and buildings) and their entrances. This supersedes the amorphous list of locations and entrances provided in version 5. An address may be<br />
<ul><br />
<li>just a postal address for correspondence, in which no location or entrances will be included in the address data</li><br />
<li>a postal address with a corresponding location on the ground (possibly with entrances)</li><br />
<li>just a location (and possibly its entrances), where the intention is to show the location on a map, but to direct post to a central address in a second address element, or occasionally that a postal address is not available for the location.</li><br />
</ul><br />
<br />
Each element contains a <strong>type</strong> field whose value is one of the keys in the following table, and then a key/value pair according to the type, as follows:<br />
<br />
<table class="wikitable"><br />
<tr><br />
<td><br />
<strong>key</strong></td><br />
<td><br />
<strong>value</strong></td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
maildrop</td><br />
<td><br />
string</td><br />
<td><br />
for parts of an address such as a room number or a PO Box number</td><br />
</tr><br />
<tr><br />
<td><br />
building</td><br />
<td><br />
string</td><br />
<td><br />
name of building</td><br />
</tr><br />
<tr><br />
<td><br />
number</td><br />
<td><br />
string</td><br />
<td><br />
location on a street, e.g. &quot;42a&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
site</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;Lords Bridge&quot;, &quot;New Museums Site&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
street</td><br />
<td><br />
string</td><br />
<td><br />
e.g. &quot;Downing Place&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
street2</td><br />
<td><br />
string</td><br />
<td><br />
occasionally a second street is part of the address</td><br />
</tr><br />
<tr><br />
<td><br />
smallplace</td><br />
<td><br />
string</td><br />
<td><br />
where place is a local village</td><br />
</tr><br />
<tr><br />
<td><br />
place</td><br />
<td><br />
string</td><br />
<td><br />
usually &quot;Cambridge&quot;</td><br />
</tr><br />
<tr><br />
<td><br />
county</td><br />
<td><br />
string</td><br />
<td><br />
rarely needed</td><br />
</tr><br />
<tr><br />
<td><br />
postcode</td><br />
<td><br />
string</td><br />
<td><br />
&nbsp;</td><br />
</tr><br />
<tr><br />
<td><br />
location</td><br />
<td><br />
location object</td><br />
<td><br />
see [[#Fields_common_to_all_geographical_objects|above]]. This is an excerpted geographical location object. There will only be at most one location object per address.</td><br />
</tr><br />
<tr><br />
<td><br />
entrance</td><br />
<td><br />
entrance object</td><br />
<td><br />
see [[#entrance|above]]. This is an excerpted geographical entrance object. There may be multiple entrance elements per address, but there will never be an entrance object in an address if there is no location object preceding it for the same address. Conversely, location elements do not have any entrance elements preceding them.</td><br />
</tr><br />
</table><br />
<br />
Some examples:<br />
<ul><br />
<li><br />
Hamilton Kerr Institute:<br /><br />
[ {&quot;type&quot;: &quot;street&quot;, &quot;street&quot;: &quot;Mill Lane&quot;},<br/>&nbsp;{&quot;type&quot;: &quot;smallplace&quot;, &quot;smallplace&quot;: &quot;Whittlesford&quot;},<br/>&nbsp;{&quot;type&quot;: &quot;place&quot;, &quot;place&quot;: &quot;Cambridge&quot;},<br/>&nbsp;{&quot;type&quot;: &quot;postcode&quot;, &quot;postcode&quot;: &quot;CB22 4NE&quot;}&nbsp;]</li><br />
<li><br />
Division of Anaesthesia<br /><br />
[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"maildrop",&nbsp;"maildrop":&nbsp;"Box&nbsp;93"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"maildrop",&nbsp;"maildrop":&nbsp;"Level&nbsp;4"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"site",&nbsp;"site":&nbsp;"Addenbrooke's&nbsp;Hospital"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"street",&nbsp;"street":&nbsp;"Hills&nbsp;Road"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"place",&nbsp;"place":&nbsp;"Cambridge"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"postcode",&nbsp;"postcode":&nbsp;"CB2&nbsp;2QQ"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"location",&nbsp;"location":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"building",&nbsp;"ref":&nbsp;"H132",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.17525,&nbsp;"lon":&nbsp;0.141464,&nbsp;"id":&nbsp;1643255315&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"H131-A",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"Addenbrooke's&nbsp;Hospital&nbsp;Main&nbsp;Entrance",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.175206,&nbsp;"lon":&nbsp;0.140538,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"direction":&nbsp;104,&nbsp;"user":&nbsp;"f",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;1643254795,&nbsp;<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;true&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance","ref":&nbsp;"H-A",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.176241,&nbsp;"lon":&nbsp;0.144354,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"direction":&nbsp;15,&nbsp;"user":&nbsp;"fbv",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;664530277,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;false<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;...<br/><br />
]</li><br />
</ul><br />
<br />
Here is a complete example record (for the Department of Anglo-Saxon, Norse and Celtic). Remember that all result records will be presented in an array, even if there is only one of them.<br />
<br />
&nbsp;&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"institution",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"inst":&nbsp;"asnc",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"prefix":&nbsp;"Department&nbsp;of",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"Anglo-Saxon,&nbsp;Norse&nbsp;and&nbsp;Celtic",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"sd":&nbsp;"asnc",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"role":&nbsp;"academic",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;"info":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"address",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"address":&nbsp;[<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"number",&nbsp;"number":&nbsp;"9"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"street",&nbsp;"street":&nbsp;"West&nbsp;Road"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"place",&nbsp;"place":&nbsp;"Cambridge"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"postcode",&nbsp;"postcode":&nbsp;"CB3&nbsp;9DP"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"location",&nbsp;"location":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"building",&nbsp;"ref":&nbsp;"S040",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"Faculty&nbsp;of&nbsp;English",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.20246,&nbsp;"lon":&nbsp;0.108541,&nbsp;"id":&nbsp;26378099&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"S040-A",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.202422,&nbsp;"lon":&nbsp;0.108616,&nbsp;"direction":&nbsp;-169,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"user":&nbsp;"f",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;1487638771,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;true&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"S-C",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.202752,&nbsp;"lon":&nbsp;0.108839,&nbsp;"direction":&nbsp;94,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"user":&nbsp;"fb",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;961417125,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;false<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"entrance",&nbsp;"entrance":&nbsp;{<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"type":&nbsp;"entrance",&nbsp;"ref":&nbsp;"S-E",<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"lat":&nbsp;52.202702,&nbsp;"lon":&nbsp;0.108056,&nbsp;"direction":&nbsp;94,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"user":&nbsp;"fbv",&nbsp;"primitive":&nbsp;"n",&nbsp;"id":&nbsp;961417126,<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"entrance":&nbsp;"main",&nbsp;"door":&nbsp;false&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;]<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"phone",&nbsp;"phone":&nbsp;"+44&nbsp;1223&nbsp;335079"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"fax",&nbsp;"fax":&nbsp;"+44&nbsp;1223&nbsp;335092"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"email",&nbsp;"email":&nbsp;"asnc@hermes.cam.ac.uk"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"url",&nbsp;"url":&nbsp;"http:\/\/www.asnc.cam.ac.uk\/"&nbsp;},<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;"type":&nbsp;"url",&nbsp;"url":&nbsp;"http:\/\/www.asnc.cam.ac.uk\/people\/index.htm",&nbsp;"role":&nbsp;"Contacts"&nbsp;}<br/><br />
&nbsp;&nbsp;&nbsp;&nbsp;]<br/><br />
&nbsp;&nbsp;}<br/><br />
<br />
==Coordinates==<br />
<br />
There are very few real-world coordinates in the database (it doesn't, for example, include building outlines). But this information is available from the [http://wiki.openstreetmap.org/wiki/API OSM API] by reference to the OSM id in the 'id' field of all geographic entities.<br />
<br />
For building outlines, the OSM API supports:<br />
<br />
<nowiki>http://osm.org/api/0.6/way/<ID></nowiki><br />
<nowiki>http://osm.org/api/0.6/way/<ID>/full</nowiki><br />
<nowiki>http://osm.org/api/0.6/way/<ID>/relations</nowiki><br />
<br />
Note however that a building doesn't have to be just a single closed way, since it can have have holes in the area. These are handled as OSM "[http://wiki.openstreetmap.org/wiki/Relation:multipolygon multipolygons]". In essence, there is an outer way plus a number of inner ways <br />
<br />
For example, Churchill West Court (ref CHU016, http://map.cam.ac.uk/v6.json?ref=CHU016&debug=1). The Map API tells you it is a way with id 148247888 and you can plug it into the OSM API thus<br />
<br />
http://www.openstreetmap.org/api/0.6/way/148247888/full<br />
<br />
returning<br />
<br />
<pre><nowiki><br />
<osm version="0.6" generator="OpenStreetMap server"><br />
<node id="1613469175" lat="52.2128314" lon="0.1013427" version="1" changeset="10553242" user="davidearl" uid="3582" visible="true" timestamp="2012-01-31T20:37:02Z"/><br />
<node id="1613469065" lat="52.2127198" lon="0.101803" version="1" changeset="10553242" user="davidearl" uid="3582" visible="true" timestamp="2012-01-31T20:36:58Z"/><br />
...<br />
<nd ref="1613469175"/><br />
<nd ref="1613469065"/><br />
...<br />
<tag k="amenity" v="university"/><br />
<tag k="building" v="yes"/><br />
<tag k="name" v="West Court"/><br />
<tag k="operator" v="Churchill College (University of Cambridge)"/><br />
<tag k="ref" v="CHU016"/><br />
</way><br />
</osm><br />
</nowiki></pre><br />
<br />
and http://www.openstreetmap.org/api/0.6/way/148247888/relations gets<br />
<br />
<pre><nowiki><br />
<osm version="0.6" generator="OpenStreetMap server"><br />
<relation id="1999559" visible="true" timestamp="2012-01-31T20:40:32Z" version="1" changeset="10553242" user="davidearl" uid="3582"><br />
<member type="way" ref="148247888" role="outer"/><br />
<member type="way" ref="148248147" role="inner"/><br />
<tag k="type" v="multipolygon"/><br />
</relation><br />
</osm><br />
</nowiki></pre><br />
<br />
telling you it is a multipolygon outer, and giving the info to traverse to the inner as above.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Tile_API&diff=739
The Tile API
2017-10-20T22:43:48Z
<p>dje39: </p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use this API.<br />
<br />
The map is assembled from a grid of image &quot;tiles&quot;, each a 256x256 pixel&nbsp;PNG format image representing a small portion of the map in [http://en.wikipedia.org/wiki/Mercator_projection spherical Mercator projection]. This is so that as it is panned, images can be loaded or dropped to keep them relevant to the area on view and therefore keep browser memory, bandwidth and download times under control. There is a separate set of tiles for each zoom level. Each higher zoom level doubles the scale and quadruples the number of tiles needed to represent the same area.<br />
<br />
While in principle we could use zoom levels from 1, the whole world, to a very large number, in practice the tiles for the University are only generated for levels 13 to 19, so the user should be constrained from going beyond these limits (zoom 19 is equivalent to a scale of about 1 tile to 46m, 0.18m per pixel or 0.66m per mm on a typical display).<br />
<br />
Similarly, we don&#39;t store tiles for the whole world. We only store an area about 8km square for each zoom level centred on western Cambridge covering most of the University's estate:<br />
<br />
<table class="wikitable"><br />
<br />
<tr><br />
<th><br />
&nbsp;</th><br />
<th><br />
<strong>latitude / longitude</strong></th><br />
<th><br />
<strong>tile number at zoom 13</strong></th><br />
<th><br />
<strong>tile number at zoom 19</strong></th><br />
</tr><br />
<tr><br />
<td><br />
<strong>west</strong></td><br />
<td><br />
-0.0025440</td><br />
<td><br />
4086</td><br />
<td><br />
262141</td><br />
</tr><br />
<tr><br />
<td><br />
<strong>east</strong></td><br />
<td><br />
0.1767487</td><br />
<td><br />
4099</td><br />
<td><br />
262401</td><br />
</tr><br />
<tr><br />
<td><br />
<strong>north</strong></td><br />
<td><br />
52.2419705</td><br />
<td><br />
2697</td><br />
<td><br />
172607</td><br />
</tr><br />
<tr><br />
<td><br />
<strong>south</strong></td><br />
<td><br />
52.1594374</td><br />
<td><br />
2699</td><br />
<td><br />
172802</td><br />
</tr><br />
</table><br />
<br />
Map tiles are retrieved using URLs thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/tiles/</nowiki>''z''/''x''/''y''.png<br />
<br />
where&nbsp;<br />
* z is the zoom level<br />
* x is the tile number in the east/west direction<br />
* y is the tile number in the north/south direction<br />
<br />
This is a [http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames conventional form] adopted among others by OpenStreetMap for tile presentation. That page also gives the formulae for converting between latitude/longitude and tile number. Rather than managing tiles directly, one could instead present the map itself using an IFRAME as described in [[The Embedding API ]] and the search/text information in a custom form using the [[The Database API]]. The same form of URL is also used by [http://openlayers.org OpenLayers] (amongst other interfaces) to display maps; most such interfaces let you plug in the prefix part of the url so that tiles can be obtained from arbitrary sources, and the URLs above are compatible with that. &nbsp;It is also possible to overlay information on the tiles obtained from OpenStreetMap&#39;s tile server or even on a Google map (whose tiles also use the same projection and numbering scheme). In addition, these tiles can be used with stand-alone programs that expect the OpenStreetMap conventions - for example they have been used with both [https://itunes.apple.com/gb/app/openmaps/id359719250?mt=8 OpenMaps] and [https://itunes.apple.com/gb/app/globalscout/id395216691?mt=8 GlobalScout] under iOS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Export&diff=738
Map Export
2017-10-20T22:42:35Z
<p>dje39: </p>
<hr />
<div>The University Map's export/print pages let you make an extract of the map in a variety of scales and formats.<br />
<br />
You can get: <br />
<br />
* at its simplest, just the map you are looking at fitted to an A4 page in a PDF file, which you can then print or pass on.<br />
<br />
* a similar PDF A4 page page but where you choose the scale, orientation, area and information included.<br />
<br />
* a PNG image file suitable for putting on another web site (though if you want to email or include a map in a web site, consider [[The_Map_URL_API|linking to]] or [[The_Embedding_API|embedding]] the main map so you always get the most up to date version - if you want to mark on top, you can also do this using an embedded map). This is somewhat similar to doing a screen shot of the map.<br />
<br />
* a map extract for use in publications: a PDF file of an exact physical size suitable for placement in a page makeup program such as Adobe InDesign, Quark XPress or Serif Page Plus.<br />
<br />
To start exporting a map extract, choose the Export/Print button above the map's search box, or '''Export/Print''' from the '''More''' menu in the main University map at https://map.cam.ac.uk<br />
<br />
<div id='step-1'></div><br />
==Choose your format==<br />
<br />
When you start Export/Print, first choose the format. <br />
<br />
If the map has any annotation overlaid (markers, pins, entrances or annotation files), you can also choose whether or not to include it.<br />
<br />
Previously exported extracts will also appear here if you ask to be remembered at the end of the process. Map extracts are stored for seven days, after which they will disappear from this panel. You can forward links to them for others to download during that time if you wish.<br />
<br />
* '''Quick Print''' has no further options. It just produces the section of the map you are looking at as a PDF file fitted to an A4 page and search results, if any, on a second page.<br />
<br />
* '''PDF A4 page''' is similar, but it works the other way round: you choose a region of the map which will fill the available space on the page. Both these formats include a page margin, scale bar and the necessary attribution.<br />
<br />
* '''PNG image''' produces just the map extract as an image. You choose the size (in pixels).<br />
<br />
* '''PDF extract''' is similar, but produces a scalable vector PDF file instead of an image, of a specified physical size in millimetres with no borders or margins. Such files are suited to dropping into layouts in page makeup applications.<br />
<br />
<div id='step-3-pdfpage'></div><br />
<br />
==PDF A4 page options==<br />
<br />
===Choose area===<br />
<br />
After selecting the '''PDF A4 page''' format, you are presented with an orange box overlaid on the map representing the available paper area for the map you were looking at. The map is zoomed out to do this, otherwise the box tends to be unhelpfully bigger than the browser window.<br />
<br />
Drag this box around to select the area which will be extracted.<br />
<br />
You can also change the paper orientation using the buttons in the left side panel. If there were search results available, you can also choose to put them on the same sheet, separate sheet, or not include them.<br />
<br />
Finally if you zoom in or out you can change which map scale, and therefore level of detail, you want (normally it will be the scale your started with). The more zoomed in you are, the larger the scale and the more detail the map shows. However, because it is a larger scale, you can fit less ground area on a given size of paper.<br />
<br />
There are 7 zoom levels, which for technical reasons are numbered 13 to 19, 19 being the largest scale. On a typical monitor, and on paper, zoom 15 (with a 500m scale bar in the top right) is approximately 1:10,000. Each zoom in doubles the scale, so zoom 19 is about 1:625.<br />
<br />
<div id='step-3-png'></div><br />
<br />
==PNG image options==<br />
<br />
===Choose area===<br />
<br />
The area selection for a PNG image is not determined by any paper size, but by pixel dimensions. <br />
<br />
You can enter these by typing, or resize the box using the handles provided. Handles are the orange blobs at each corner and centre of each side. Drag one of these to enlarge or reduce the box from that corner or side.<br />
<br />
As for PDF, drag the orange box itself to choose the area to be extracted.<br />
<br />
<div id='step-2-pdfextract'></div><br />
<br />
==PDF extract options==<br />
<br />
===Choose map===<br />
<br />
For PDF extracts there is an additional step: choosing the map. This option offers two additional behind-the-scenes maps to extract from, as well as the online map. Examples are shown below.<br />
<br />
<div id='step-3-pdfextract'></div><br />
<br />
===Choose area===<br />
<br />
Once you've chosen the map for a PDF extract, choose the area as with the other formats, by dragging the orange box.<br />
<br />
Also choose the size of your extáract. This can be arbitrarily large and because it is mostly formed from vector data it will happily enlarge, even to poster sizes. The size is specified in millimetres so that you can relate it to available space on a physical page being prepared with a page makeup application. You don't actually have to use it at that physical size, but if you make it too small the text would be unreadable, and of course, the scale would not then be accurate.<br />
<br />
===Extra map examples===<br />
<br />
Two additional maps other than the online map are available when using '''PDF Extract'''.<br />
<br />
At a scale of 1:3,7500, the central area map covers roughly from Sidgwick Site in the west to the Chemistry Laboratory in the east. It's intended to highlight the central city University sites - it names colleges but does not show their buildings or outlines. In its entirety it fits on landscape A4 and is primarily intended for use in the University's paper map. Example extract:<br />
<br />
[[File:university-map-3750-example.png]]<br />
<br />
At 1:7,500, the simplified map is the basis for the main paper map but omits all but main street names, and is therefore less cluttered and perhaps more suitable for annotating on top. Example extract:<br />
<br />
[[File:university-map-7500-example.png]]<br />
<br />
For comparison, the online map's zoom level 15 (indicated in the URL and by the 500m scale size in the top right) is approximately 1:10,000 on a typical monitor or when printed (each zoom level changes the scale by a factor of 2).<br />
<br />
<div id='step-4-wait'></div><br />
<br />
==Making the extract==<br />
<br />
===Wait for your map===<br />
<br />
Once you have started to make your file, your request joins a queue. Usually it only takes a few seconds, but if there are several people wanting extracts at the same time, it may take longer.<br />
<br />
If you don't want to wait, this page provides the means to send you an email when it is done, or a link for you to check later.<br />
<br />
If you say 'Remember me', it will also show you all your previous extracts which are still available (they are kept for seven days) at the beginning of the Export/print process.<br />
<br />
<div id='step-5-collect'></div><br />
===Collect your map===<br />
<br />
Once the map extract is complete, the waiting symbol turns into a download botton. Press this to collect your file. You can still send its link by email to collect it later if you want, and remember all your Export files here.<br />
<br />
<div id='step-45-cookies'></div><br />
==Cookies and privacy==<br />
<br />
When you say 'Remember me' a cookie is placed on your computer. This is in addition to the other cookies used by the map and requires your permission.<br />
<br />
The cookie is called 'exportuser'. It stores only a unique random code which is used to identify on the server export extracts requested from your browser.<br />
<br />
(This means 'Remember me' only works if you use the same computer/browser the next time: we specifically don't use University logins because the service is also intended for use by visitors).<br />
<br />
Whether or not you remember this number in your browser, the requests and extracts are stored for seven days along with <br />
* the information needed to make the extract (area, search information, settings etc)<br />
* the IP address from which it was requested, and <br />
* the time and date.<br />
<br />
While not made explicitly public, a map extract is not treated as private information, and intentionally, anyone who knows the relevant link will be able to access it. As these are not guessable, this would usually only be map administrators and people you specifically give the link to.<br />
<br />
==Attribution==<br />
<br />
When using the map in a publication (whether online or on paper), your document needs to include an attribution to OpenStreetMap, on which the map is based, and we would appreciate acknowledgement of the source. The A4 PDFs already include such an acknowledgement, but the PDF and PNG extracts do not, to give you maximum flexibility to incorporate the map as you wish in your publications.<br />
<br />
Please quote the following:<br />
<br />
Map base data copyright © OpenStreetMap contributors, including<br />
University of Cambridge, licensed ODbL v1.0. Map presentation<br />
copyright © [year] University of Cambridge.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=737
UCamGeoJSON
2017-10-20T22:41:07Z
<p>dje39: /* Cross-site scripting */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [https://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>https://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [https://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at https://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [https://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[https://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>https://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
: Note also that it is not permissible to load data via http from any https site. As the map is served over https at https://map.cam.ac.uk, your annotation must also be fetched over https, as must any images it references.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy - it asks the map server to fetch the data rather than youir browser doing it directly. This means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially unprotected files only accessible within the University network by any arbitrary site outside the University.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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 it is not possible to tell you where. Paste your JSON link into the browser and complete the login there, then try the map URL again.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS; thankfully, these are now rare.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=736
UCamGeoJSON
2017-10-20T22:39:57Z
<p>dje39: /* Cross-site scripting */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [https://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>https://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [https://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at https://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [https://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[https://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>https://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
: Note also that it is not permissible to load data via http from any https site, so,mbecause the map is served over https at https://map.cam.ac.uk, your annotation must also be fetched over https, as must any images it references.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy - it asks the map server to fetch the data rather than youir browser doing it directly. This means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially unprotected files only accessible within the University network by any arbitrary site outside the University.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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 it is not possible to tell you where. Paste your JSON link into the browser and complete the login there, then try the map URL again.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS; thankfully, these are now rare.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=735
UCamGeoJSON
2017-10-20T22:37:09Z
<p>dje39: /* properties applied to images/icons/markers */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [https://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>https://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [https://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at https://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [https://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[https://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
: Note also that it is not permissible to load data via http from any https site, so if you use https://map.cam.ac.uk, your annotation must also be fetched over https, as must any images it references. Otherwise, this will fall back to the case below.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy - it asks the map server to fetch the data rather than youir browser doing it directly. This means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially unprotected files only accessible within the University network by any arbitrary site outside the University.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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 it is not possible to tell you where. Paste your JSON link into the browser and complete the login there, then try the map URL again.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS; thankfully, these are now rare.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=734
UCamGeoJSON
2017-10-20T22:36:36Z
<p>dje39: </p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [https://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>https://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [https://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [https://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[https://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
: Note also that it is not permissible to load data via http from any https site, so if you use https://map.cam.ac.uk, your annotation must also be fetched over https, as must any images it references. Otherwise, this will fall back to the case below.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy - it asks the map server to fetch the data rather than youir browser doing it directly. This means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially unprotected files only accessible within the University network by any arbitrary site outside the University.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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 it is not possible to tell you where. Paste your JSON link into the browser and complete the login there, then try the map URL again.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS; thankfully, these are now rare.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=733
Map Annotation
2017-10-20T22:34:47Z
<p>dje39: /* Where? */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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: https://map.cam.ac.uk/Department+of+Geography . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also if you only want to put some pins on the map, you can do this directly from the map: click where you want them and choose the pin icon (draw marker). Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another https URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (Raven login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>https://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [https://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [https://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>https://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
https://map.cam.ac.uk/#https://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[https://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io dillinger.io]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL and is served over https. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link, Hover & Pop-up ====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the ''Markdown'' box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io/ dillinger.io].<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mind some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=732
Map Annotation
2017-10-20T22:33:49Z
<p>dje39: </p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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: https://map.cam.ac.uk/Department+of+Geography . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also if you only want to put some pins on the map, you can do this directly from the map: click where you want them and choose the pin icon (draw marker). Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (Raven login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>https://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [https://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [https://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>https://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
https://map.cam.ac.uk/#https://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[https://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io dillinger.io]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL and is served over https. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link, Hover & Pop-up ====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the ''Markdown'' box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io/ dillinger.io].<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>https://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mind some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=731
The Embedding API
2017-10-20T22:29:23Z
<p>dje39: /* PHP */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress or Falcon), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>https://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>https://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>https://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed for the University Map is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]https://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from https://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access,<br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('https://map.cam.ac.uk/*', 'https://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=730
The Embedding API
2017-10-20T22:28:53Z
<p>dje39: /* Plugin */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress or Falcon), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>https://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>https://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>https://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed for the University Map is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]https://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from https://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access,<br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=729
The Embedding API
2017-10-20T22:28:21Z
<p>dje39: /* Wordpress */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress or Falcon), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>https://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>https://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>https://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed for the University Map is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]https://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access, <br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=728
The Embedding API
2017-10-20T22:27:53Z
<p>dje39: /* Basic information */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress or Falcon), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>https://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>https://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>https://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed for the University Map is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]http://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access, <br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=727
The Embedding API
2017-10-20T22:27:16Z
<p>dje39: /* Basic information */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress or Falcon), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>HTTPS://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>https://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>https://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed for the University Map is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]http://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access, <br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=726
The Embedding API
2017-10-20T22:26:36Z
<p>dje39: /* HTTPS */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress or Falcon), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>http://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>http://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed for the University Map is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]http://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access, <br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=725
The Embedding API
2017-10-20T22:25:18Z
<p>dje39: /* IFRAME (manually embedding the map) */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>https://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
===HTTPS===<br />
<br />
Note that if your page is served using HTTPS, you will also need to use https to retrieve the map, otherwise users will receive messages warning about mixed and unprotected content on the page:<br />
<br />
<iframe src="<strong>https</strong>://map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
Firefox version 23 (and presumably later) actually blocks such content entirely if http is used in the iframe src when embedding in an https page.<br />
<br />
If you can serve the same pages using either protocol, you can arrange for the map to serve using the same protocol as the page in which it is embedded by omitting the protocol, just starting with the two slashes, thus:<br />
<br />
<iframe src="<strong>//</strong>map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress or Falcon), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>http://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>http://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed for the University Map is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]http://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access, <br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Map_URL_API&diff=724
The Map URL API
2017-10-20T22:23:52Z
<p>dje39: Https</p>
<hr />
<div>URLs have the following structure. Note that in all cases where a query string follows a directory the separating &#39;/&#39; is optional (i.e. <strong><nowiki>https://map.cam.ac.uk/x/?</nowiki>q=s</strong> is exactly the same as <strong><nowiki>https://map.cam.ac.uk/x?</nowiki>q=s</strong>).<br />
<br />
<table class="wikitable"><br />
<tr><br />
<th><br />
<strong>URL</strong></th><br />
<th><br />
<strong>Description</strong></th><br />
<th><br />
<strong>Examples</strong></th><br />
</tr><br />
<tr><br />
<td style="vertical-align: top; "><br />
<nowiki>https://map.cam.ac.uk/</nowiki></td><br />
<td style="vertical-align: top; "><br />
displays the home page of the University map</td><br />
<td style="vertical-align: top; "><br />
https://map.cam.ac.uk/</td><br />
</tr><br />
<tr><br />
<td style="vertical-align: top; "><br />
<nowiki>https://map.cam.ac.uk/</nowiki><em>name</em></td><br />
<td style="vertical-align: top; "><br />
<p><br />
displays the map homed in on the item called <em>name</em>. <em>name</em> is URL encoded text for any entity the map can locate, ignoring case and punctuation and including any synonymous forms (such as Road vs. Rd). In fact this is simply an neater abbreviation for &#39;<nowiki>http://map.cam.ac.uk/?</nowiki>q=<em>name</em>&#39; (see below).</p><br />
<p><br />
<strong>If you want to link to a map on the centrally hosted site, this is the best kind of URL to use. </strong>But consider embedding a map: see below.</p><br />
<p><br />
Older names will still respond to searches providing a cross reference is included in the database (as it was in the older system), or the old name is present in the &#39;AKA&#39; field.</p><br />
</td><br />
<td style="vertical-align: top; "><br />
<p><br />
https://map.cam.ac.uk/Lucy+Cavendish+College</p><br />
<p><br />
https://map.cam.ac.uk/austin%20building</p><br />
<p><br />
https://map.cam.ac.uk/Fenner%27s</p><br />
<p><br />
https://map.cam.ac.uk/Tennis+Court+Road</p><br />
<p><br />
https://map.cam.ac.uk/fitzwilliam+st</p><br />
<p><br />
https://map.cam.ac.uk/queens+college<br /><br />
(note the absence of apostrophe).</p><br />
</td><br />
</tr><br />
<tr><br />
<td style="vertical-align: top; "><br />
<nowiki>https://map.cam.ac.uk/?</nowiki>ref=<em>ref</em></td><br />
<td style="vertical-align: top; "><br />
displays the map homed in on the item(s) referenced&nbsp;<em>ref</em>. References are geographical information and refer to entrances, buildings and sites/colleges as indicated by the ref=... tag on the corresponding OpenStreetMap data. <em>ref</em> can also be a list of references separated by &#39;|&#39; (up to 25 can be requested at once). Where buildings or sites are selected the corresponding main entrances are also displayed.</td><br />
<td style="vertical-align: top; "><br />
<p><br />
https://map.cam.ac.uk/?ref=STEDMUNDS019<br /><br />
(which is the Library building in St Edmund&#39;s College)</p><br />
<p><br />
https://map.cam.ac.uk/?ref=WOLFSON--W<br /><br />
(Wolfson College W staircase)<br /><br />
&nbsp;</p><br />
</td><br />
</tr><br />
<tr><br />
<td style="vertical-align: top; "><br />
<nowiki>https://map.cam.ac.uk/?</nowiki>inst=<em>inst</em></td><br />
<td style="vertical-align: top; "><br />
displays the map homed in on institution(s) identified by&nbsp;<em>inst</em>,<em>&nbsp;</em>the institution code, which is case insensitive, or a list of these separated by &#39;|&#39; (up to 25 can be requested at once).</td><br />
<td style="vertical-align: top; "><br />
<p><br />
https://map.cam.ac.uk/?inst=CS<br /><br />
(computing service)</p><br />
<p><br />
https://map.cam.ac.uk/?inst=cs<br /><br />
(ditto)</p><br />
<p><br />
https://map.cam.ac.uk/?inst=lcc<br /><br />
(Lucy Cavendish College)</p><br />
<p><br />
https://map.cam.ac.uk/?inst=lucy-cav|joh<br /><br />
(lucy Cavendish and St John&#39;s Colleges)</p><br />
</td><br />
</tr><br />
<tr><br />
<td style="vertical-align: top; "><br />
<nowiki>https://map.cam.ac.uk/?</nowiki>q=<em>search</em><br /><br />
[&amp;one=list]<br /><br />
[&amp;partial<em>=</em>yes]<br /><br />
[&amp;filter=<em>filter</em>]</td><br />
<td style="vertical-align: top; "><br />
<p><br />
displays the map page with results of the search for the URL encoded string&nbsp;<em>search</em>. Multiple search strings may be given separated by &#39;|&#39;</p><br />
<p><br />
&#39;one=list&#39; is optional and if given overrides the default behaviour (which is to display the single result) and instead to display it as a list of results comrpsing only a single entry<i>.</i></p><br />
<p><br />
If &#39;partial=yes&#39; (or in fact, &#39;partial=anything&nbsp;else&#39;) is given results returned by the search are interpreted as a partial search, that is in the same way as typing the first few letters of a word (the last word if more than one). If not present then a match is made only on whole words (including synonymous forms and ignoring case and punctuation, but in any order).</p><br />
<br />
<p><br />
Note that as a special case for non-partial searches, if a match is found on a phrase which also has a longer phrase in which the same words appear, only the single shorter result is supplied. For example 'Austin+Building' does not return 'Austin Robinson Building'.</p><br />
<br />
<p><br />
If filter is given, only results which match the filter are returned. filter is one or more of the following, separated by vertical bar, for example &quot;filter=college|academic&quot;: <strong>college, academic, site, nonacademic, lecture, techno, street, nonuniversity</strong>.</p><br />
<p><br />
Note that if the search yields only one result and the optional parameters are omitted, then the result is identical to the URL <nowiki>https://map.cam.ac.uk/</nowiki><em>name </em>as above.</p><br />
</td><br />
<td style="vertical-align: top; "><br />
<p><br />
https://map.cam.ac.uk/?q=Lucy+Cavendish+College</p><br />
<p><br />
https://map.cam.ac.uk/?q=lucy|queens</p><br />
<p><br />
https://map.cam.ac.uk/?q=Wolfson+College&amp;one=list</p><br />
<p><br />
https://map.cam.ac.uk/?q=Do&amp;partial=yes<br /><br />
(which might yield results for Downing College, Downing Street, Downing Place, Downing Site and Doubletree by Hilton).</p><br />
<p><br />
https://map.cam.ac.uk/?q=Do<br /><br />
(produces no results)</p><br />
<p><br />
https://map.cam.ac.uk/?q=sussex&amp;filter=college</p><br />
</td><br />
</tr><br />
<tr><br />
<td style="vertical-align: top; "><br />
<p><br />
<nowiki>https://map.cam.ac.uk/?</nowiki>bb=<em>lat0,lon0,lat1,lon1</em><br /><br />
[&amp;one=list]<br /><br />
[&amp;filter=<em>filter</em>]</p><br />
</td><br />
<td style="vertical-align: top; "><br />
<p><br />
search by bounding box (specified as a pair of latitude/longitude co-ordinates) rather than text string. Note: no spaces after commas. Large bounding boxes can produce very large amounts of data, so please keep areas small (say < 500m).</p><br />
<p><br />
filter as above</p><br />
</td><br />
<td style="vertical-align: top; "><br />
https://map.cam.ac.uk/?bb=52.2021,0.1184,52.2047,0.1218</td><br />
</tr><br />
</table><br />
<br />
You can also append a ''fragment'' part to any of the URLs, that is a hash followed by further information. The fragment part comprises either several numbers, or another URL, or both (the numbers preceding the URL and separated by a comma). The numbers control where the map is displayed initially (and overrides any default arising from the specified search). A URL provides an overlay, created [[UCamGeoJSON|manually, using UCamGeoJSON]] or [[Map_Annotation|interactively using 'Annotate the map']]. The URL may also be abbreviated to an identifier (a code usually starting Y or Z) which identifies annotation stored on the University's own annotation server. For example:<br />
<br />
<nowiki><br />
https://map.cam.ac.uk/#52.206397,0.114015,16<br />
https://map.cam.ac.uk/#http://webtools.csx.cam.ac.uk/map-demo/annotation.json<br />
https://map.cam.ac.uk/#52.206397,0.114015,16,http://webtools.csx.cam.ac.uk/map-demo/annotation.json<br />
</nowiki><br />
<br />
The numeric appendices are as follows (and can be determined simply by moving the map to where you want it, adding marker(s) if required, using a click on the map, and saving the URL from the browser's address bar or the 'Link to map' button/menu.<br />
<br />
<nowiki><br />
https://map.cam.ac.uk/#z<br />
https://map.cam.ac.uk/#lat,lon<br />
https://map.cam.ac.uk/#lat,lon,z<br />
https://map.cam.ac.uk/#lat,lon,mlat,mlon<br />
https://map.cam.ac.uk/#lat,lon,z,mlat,mlon<br />
https://map.cam.ac.uk/#lat,lon,z,mlat0,mlon0,mlat1,mlon1,...</nowiki><br />
<br />
where ''z'' is the initial zoom level (from 13, furthest zoomed out to 19, furthest zoomed in), ''lat'' and ''lon'' are the latitude and longitude where the map view is centred, and ''mlat'' and ''mlon'' are the latitude and longitude where a marker should be displayed, repeated as required for further markers.<br />
<br />
'''nofont''': You can also include a query parameter nofont (though this would only be needed in very unusual situations). When on, the University corporate fonts are not loaded. This is useful in circumstances where links to external URLs are not permitted (e.g. when embedding the map on a cafe-style login page). nofont=1 (or any non-zero, non-empty value) turns it on and nofont=0 turns it off.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Main_Page&diff=723
Main Page
2017-10-20T22:18:21Z
<p>dje39: Https</p>
<hr />
<div>This wiki contains information about the OpenStreetMap-based University Map. This information is aimed at anyone who wants to use the more advanced facilities that the map offers, or who want to contribute to the underlying OpenStreetMap data on which the map is based. The map itself provides [https://map.cam.ac.uk/help/ help on using the standard map service].<br />
<br />
The map can be accessed at https://map.cam.ac.uk/. <br />
<br />
There is an '''[[Introduction and examples|introduction and set of examples]]''' of what you can do with the map that you might want to start with.<br />
<br />
Please report problems, issues, etc. to the UCS Service Desk [mailto:service-desk@ucs.cam.ac.uk service-desk@ucs.cam.ac.uk].<br />
<br />
==Reference==<br />
<br />
; '''[[The Map URL API|Linking to the map]]''' : How to link to the map to display various things<br />
<br />
; '''[[The Embedding API|Embedding the map]]''' : How to easily embed the maps in other web pages <br />
<br />
; '''[[Map_Annotation|Interactive annotation]]''' : How to interactively add points, lines, areas and text to a map that others can display, using 'Annotate the map'<br />
<br />
; '''[[UCamGeoJSON|Programmatic annotation]]''' : How to automatically add annotation information to the map (using [[UCamGeoJSON]])<br />
<br />
; '''[[Map_Export|Exporting and printing the map]]''' : How to download sections of the map in PDF or PNG formats for off-line use and incorporation in printed materials<br />
<br />
; '''[[The Tile API|Using the tiles]]''' : How to use the map tiles provided to create your own maps when other approaches are not suitable<br />
<br />
; '''[[The Database API|Accessing the database]]''' : How to access the information database underlying the map<br />
<br />
; '''[[Terms and conditions, Copyright, Fair Use, etc.]]''' : The conditions under which we provide the map and its associated services, what you need to do if you use it, etc.<br />
<br />
; '''[[Accessing OpenStreetMap]]''' : How to interact with the data in OpenStreetMap<br />
<br />
; '''[[Case Studies]]''' : Examples and case studies from people using the map<br />
<br />
; '''[[FAQ]]''' : Frequently (or at least occasionally) asked questions</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=722
Map Annotation
2017-07-05T17:30:13Z
<p>dje39: /* Introduction */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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.<br />
<br />
Also if you only want to put some pins on the map, you can do this directly from the map: click where you want them and choose the pin icon (draw marker). Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (Raven login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [http://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>http://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
http://map.cam.ac.uk/#http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[http://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io dillinger.io]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link, Hover & Pop-up ====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the ''Markdown'' box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io/ dillinger.io].<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mid some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=721
UCamGeoJSON
2017-07-05T17:20:58Z
<p>dje39: /* Login-protected sources */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [https://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[https://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
: Note also that it is not permissible to load data via http from any https site, so if you use https://map.cam.ac.uk, your annotation must also be fetched over https, as must any images it references. Otherwise, this will fall back to the case below.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy - it asks the map server to fetch the data rather than youir browser doing it directly. This means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially unprotected files only accessible within the University network by any arbitrary site outside the University.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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 it is not possible to tell you where. Paste your JSON link into the browser and complete the login there, then try the map URL again.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS; thankfully, these are now rare.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=720
UCamGeoJSON
2017-07-05T17:18:54Z
<p>dje39: /* Login-protected sources */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [https://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[https://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
: Note also that it is not permissible to load data via http from any https site, so if you use https://map.cam.ac.uk, your annotation must also be fetched over https, as must any images it references. Otherwise, this will fall back to the case below.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy - it asks the map server to fetch the data rather than youir browser doing it directly. This means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially unprotected files only accessible within the University network by any arbitrary site outside the University.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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 it is not possible to tell you where. Paste your JSON link into the browser and complete the login there, then try the map URL again.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=719
UCamGeoJSON
2017-07-05T17:17:05Z
<p>dje39: /* Cross-site scripting */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [https://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[https://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
: Note also that it is not permissible to load data via http from any https site, so if you use https://map.cam.ac.uk, your annotation must also be fetched over https, as must any images it references. Otherwise, this will fall back to the case below.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy - it asks the map server to fetch the data rather than youir browser doing it directly. This means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially unprotected files only accessible within the University network by any arbitrary site outside the University.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=718
UCamGeoJSON
2017-07-05T17:14:00Z
<p>dje39: /* Cross-site scripting */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [https://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[https://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
: Note also that it is not permissible to load data via http from any https site, so if you use https://map.cam.ac.uk, your annotation must also be fetched over https, as must any images it references. Otherwise, this will fall back to the case below.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy - it asks the map server to fetch the data rather than youir browser doing it directly. This means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially by any arbitrary site that is not the map.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=717
UCamGeoJSON
2017-07-05T17:12:10Z
<p>dje39: /* Cross-site scripting */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [http://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[http://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
: Note also that it is not permissible to load data via http from any https site, so if you use https://map.cam.ac.uk, your annotation must also be fetched over https, as must any images it references. Otherwise, this will fall back to the case below.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy - it asks the map server to fetch the data rather than youir browser doing it directly. This means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially by any arbitrary site that is not the map.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=716
UCamGeoJSON
2017-07-05T17:07:53Z
<p>dje39: /* Adapters */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>https://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
https://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [http://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[http://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy, which means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially by any arbitrary site that is not the map.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=715
UCamGeoJSON
2017-07-05T17:07:23Z
<p>dje39: /* Using UCamGeoJSON */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>https://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>https://map.cam.ac.uk/#https://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>https://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [https://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>https://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>https://map.cam.ac.uk/#https://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='https://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='https://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>https://map.cam.ac.uk/#z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>https://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>http://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
http://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [http://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[http://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy, which means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially by any arbitrary site that is not the map.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=714
UCamGeoJSON
2017-07-05T17:05:53Z
<p>dje39: /* Login-protected sources */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>http://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>http://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>http://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='http://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='http://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>http://map.cam.ac.uk/#z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>http://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
http://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [http://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[http://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy, which means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially by any arbitrary site that is not the map.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>https://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=713
UCamGeoJSON
2017-07-05T17:05:25Z
<p>dje39: /* Cross-site scripting */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>http://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>http://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>http://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='http://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='http://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>http://map.cam.ac.uk/#z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>http://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
http://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [http://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[http://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that the now ancient and unsupported, but still sometimes used, Internet Explorer 8 (and earlier) does not support CORS.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter proxy, which means making two attempts, but will work in most instances (providing the JSON contains a "signature" - see below). However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course, and the JSON must also contain a "signature".<br />
<br />
To use the CORS adapter proxy, your UCamGeoJSON must include a field "signature" with the value "UCamGeoJSON" (or some string containing that). Files produced with the annotation editor automatically do so. e.g.<br />
<br />
{"signature":"UCamGeoJSON Department-of-Physics",<br />
...}<br />
<br />
This is a precaution to prevent the adapter being used to proxy arbitrary files, especially by any arbitrary site that is not the map.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>http://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=712
UCamGeoJSON
2016-11-15T21:45:45Z
<p>dje39: /* properties applied to both text and images */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>http://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>http://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>http://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='http://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='http://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>http://map.cam.ac.uk/#z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| popup<br />
| Content to be displayed in a pop-up "speech bubble" when the user clicks on the annotation. This can be either plain text or formatted rich text and images if '''popupmarkdown''' is also set to true.<br />
|-<br />
| popupmarkdown<br />
| If set to true, '''popup''' is interpreted as [https://daringfireball.net/projects/markdown/ markdown] formatted text. This allows for lots of variation in the content of the pop-up. In particular, note that markdown can also include raw HTML, and that can include an [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe IFRAME]. Iframe's content is evaluated as it is loaded, so such bubbles can include changing and real-time information.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>http://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
http://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [http://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[http://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that CORS is relatively new technology. It requires the user's browser to support CORS. Most browsers do, but notably the still widely used Internet Explorer 8 (and earlier) does not. That means you probably have to know your users.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter, which means making two attempts, but will work in most instances. However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>http://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=711
UCamGeoJSON
2016-11-15T21:36:48Z
<p>dje39: /* Initial map view */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>http://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>http://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>http://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='http://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='http://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>http://map.cam.ac.uk/#z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
* '''markdown''' is a boolean, which if present and true indicates that '''bodytext''' should be interpreted as [https://daringfireball.net/projects/markdown/ markdown], the text markup language enabling rich text and images in the information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"title": "My Overlay",<br />
"bodytext": "Here is some text which is to be <nowiki>'''bold'''</nowiki>",<br />
"markdown": true,<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>http://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
http://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [http://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[http://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that CORS is relatively new technology. It requires the user's browser to support CORS. Most browsers do, but notably the still widely used Internet Explorer 8 (and earlier) does not. That means you probably have to know your users.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter, which means making two attempts, but will work in most instances. However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>http://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=710
Map Annotation
2016-11-15T21:31:38Z
<p>dje39: /* Heading */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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.<br />
<br />
Also if you only want a single pin on the map, you can do this directly from the map: click where you want it and choose the pin icon. Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (Raven login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [http://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>http://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
http://map.cam.ac.uk/#http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[http://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io dillinger.io]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link, Hover & Pop-up ====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the ''Markdown'' box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io/ dillinger.io].<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mid some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=709
Map Annotation
2016-11-15T21:30:51Z
<p>dje39: /* Link & Hover Text */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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.<br />
<br />
Also if you only want a single pin on the map, you can do this directly from the map: click where you want it and choose the pin icon. Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (Raven login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [http://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>http://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
http://map.cam.ac.uk/#http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[http://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link, Hover & Pop-up ====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the ''Markdown'' box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. [https://daringfireball.net/projects/markdown/ Here's the documentation]. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at [http://dillinger.io/ dillinger.io].<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mid some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=708
Map Annotation
2016-11-15T21:23:45Z
<p>dje39: /* Heading */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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.<br />
<br />
Also if you only want a single pin on the map, you can do this directly from the map: click where you want it and choose the pin icon. Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (Raven login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [http://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>http://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
http://map.cam.ac.uk/#http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[http://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. [https://daringfireball.net/projects/markdown/ Here's the documentation]. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link & Hover Text====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mid some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Export&diff=707
Map Export
2016-08-20T15:54:18Z
<p>dje39: remove beta information</p>
<hr />
<div>The University Map's export/print pages let you make an extract of the map in a variety of scales and formats.<br />
<br />
You can get: <br />
<br />
* at its simplest, just the map you are looking at fitted to an A4 page in a PDF file, which you can then print or pass on.<br />
<br />
* a similar PDF A4 page page but where you choose the scale, orientation, area and information included.<br />
<br />
* a PNG image file suitable for putting on another web site (though if you want to email or include a map in a web site, consider [[The_Map_URL_API|linking to]] or [[The_Embedding_API|embedding]] the main map so you always get the most up to date version - if you want to mark on top, you can also do this using an embedded map). This is somewhat similar to doing a screen shot of the map.<br />
<br />
* a map extract for use in publications: a PDF file of an exact physical size suitable for placement in a page makeup program such as Adobe InDesign, Quark XPress or Serif Page Plus.<br />
<br />
To start exporting a map extract, choose the Export/Print button above the map's search box, or '''Export/Print''' from the '''More''' menu in the main University map at http://map.cam.ac.uk<br />
<br />
<div id='step-1'></div><br />
==Choose your format==<br />
<br />
When you start Export/Print, first choose the format. <br />
<br />
If the map has any annotation overlaid (markers, pins, entrances or annotation files), you can also choose whether or not to include it.<br />
<br />
Previously exported extracts will also appear here if you ask to be remembered at the end of the process. Map extracts are stored for seven days, after which they will disappear from this panel. You can forward links to them for others to download during that time if you wish.<br />
<br />
* '''Quick Print''' has no further options. It just produces the section of the map you are looking at as a PDF file fitted to an A4 page and search results, if any, on a second page.<br />
<br />
* '''PDF A4 page''' is similar, but it works the other way round: you choose a region of the map which will fill the available space on the page. Both these formats include a page margin, scale bar and the necessary attribution.<br />
<br />
* '''PNG image''' produces just the map extract as an image. You choose the size (in pixels).<br />
<br />
* '''PDF extract''' is similar, but produces a scalable vector PDF file instead of an image, of a specified physical size in millimetres with no borders or margins. Such files are suited to dropping into layouts in page makeup applications.<br />
<br />
<div id='step-3-pdfpage'></div><br />
<br />
==PDF A4 page options==<br />
<br />
===Choose area===<br />
<br />
After selecting the '''PDF A4 page''' format, you are presented with an orange box overlaid on the map representing the available paper area for the map you were looking at. The map is zoomed out to do this, otherwise the box tends to be unhelpfully bigger than the browser window.<br />
<br />
Drag this box around to select the area which will be extracted.<br />
<br />
You can also change the paper orientation using the buttons in the left side panel. If there were search results available, you can also choose to put them on the same sheet, separate sheet, or not include them.<br />
<br />
Finally if you zoom in or out you can change which map scale, and therefore level of detail, you want (normally it will be the scale your started with). The more zoomed in you are, the larger the scale and the more detail the map shows. However, because it is a larger scale, you can fit less ground area on a given size of paper.<br />
<br />
There are 7 zoom levels, which for technical reasons are numbered 13 to 19, 19 being the largest scale. On a typical monitor, and on paper, zoom 15 (with a 500m scale bar in the top right) is approximately 1:10,000. Each zoom in doubles the scale, so zoom 19 is about 1:625.<br />
<br />
<div id='step-3-png'></div><br />
<br />
==PNG image options==<br />
<br />
===Choose area===<br />
<br />
The area selection for a PNG image is not determined by any paper size, but by pixel dimensions. <br />
<br />
You can enter these by typing, or resize the box using the handles provided. Handles are the orange blobs at each corner and centre of each side. Drag one of these to enlarge or reduce the box from that corner or side.<br />
<br />
As for PDF, drag the orange box itself to choose the area to be extracted.<br />
<br />
<div id='step-2-pdfextract'></div><br />
<br />
==PDF extract options==<br />
<br />
===Choose map===<br />
<br />
For PDF extracts there is an additional step: choosing the map. This option offers two additional behind-the-scenes maps to extract from, as well as the online map. Examples are shown below.<br />
<br />
<div id='step-3-pdfextract'></div><br />
<br />
===Choose area===<br />
<br />
Once you've chosen the map for a PDF extract, choose the area as with the other formats, by dragging the orange box.<br />
<br />
Also choose the size of your extáract. This can be arbitrarily large and because it is mostly formed from vector data it will happily enlarge, even to poster sizes. The size is specified in millimetres so that you can relate it to available space on a physical page being prepared with a page makeup application. You don't actually have to use it at that physical size, but if you make it too small the text would be unreadable, and of course, the scale would not then be accurate.<br />
<br />
===Extra map examples===<br />
<br />
Two additional maps other than the online map are available when using '''PDF Extract'''.<br />
<br />
At a scale of 1:3,7500, the central area map covers roughly from Sidgwick Site in the west to the Chemistry Laboratory in the east. It's intended to highlight the central city University sites - it names colleges but does not show their buildings or outlines. In its entirety it fits on landscape A4 and is primarily intended for use in the University's paper map. Example extract:<br />
<br />
[[File:university-map-3750-example.png]]<br />
<br />
At 1:7,500, the simplified map is the basis for the main paper map but omits all but main street names, and is therefore less cluttered and perhaps more suitable for annotating on top. Example extract:<br />
<br />
[[File:university-map-7500-example.png]]<br />
<br />
For comparison, the online map's zoom level 15 (indicated in the URL and by the 500m scale size in the top right) is approximately 1:10,000 on a typical monitor or when printed (each zoom level changes the scale by a factor of 2).<br />
<br />
<div id='step-4-wait'></div><br />
<br />
==Making the extract==<br />
<br />
===Wait for your map===<br />
<br />
Once you have started to make your file, your request joins a queue. Usually it only takes a few seconds, but if there are several people wanting extracts at the same time, it may take longer.<br />
<br />
If you don't want to wait, this page provides the means to send you an email when it is done, or a link for you to check later.<br />
<br />
If you say 'Remember me', it will also show you all your previous extracts which are still available (they are kept for seven days) at the beginning of the Export/print process.<br />
<br />
<div id='step-5-collect'></div><br />
===Collect your map===<br />
<br />
Once the map extract is complete, the waiting symbol turns into a download botton. Press this to collect your file. You can still send its link by email to collect it later if you want, and remember all your Export files here.<br />
<br />
<div id='step-45-cookies'></div><br />
==Cookies and privacy==<br />
<br />
When you say 'Remember me' a cookie is placed on your computer. This is in addition to the other cookies used by the map and requires your permission.<br />
<br />
The cookie is called 'exportuser'. It stores only a unique random code which is used to identify on the server export extracts requested from your browser.<br />
<br />
(This means 'Remember me' only works if you use the same computer/browser the next time: we specifically don't use University logins because the service is also intended for use by visitors).<br />
<br />
Whether or not you remember this number in your browser, the requests and extracts are stored for seven days along with <br />
* the information needed to make the extract (area, search information, settings etc)<br />
* the IP address from which it was requested, and <br />
* the time and date.<br />
<br />
While not made explicitly public, a map extract is not treated as private information, and intentionally, anyone who knows the relevant link will be able to access it. As these are not guessable, this would usually only be map administrators and people you specifically give the link to.<br />
<br />
==Attribution==<br />
<br />
When using the map in a publication (whether online or on paper), your document needs to include an attribution to OpenStreetMap, on which the map is based, and we would appreciate acknowledgement of the source. The A4 PDFs already include such an acknowledgement, but the PDF and PNG extracts do not, to give you maximum flexibility to incorporate the map as you wish in your publications.<br />
<br />
Please quote the following:<br />
<br />
Map base data copyright © OpenStreetMap contributors, including<br />
University of Cambridge, licensed ODbL v1.0. Map presentation<br />
copyright © [year] University of Cambridge.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=706
The Embedding API
2016-07-25T11:38:26Z
<p>dje39: /* What is oEmbed? */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>http://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>http://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
===HTTPS===<br />
<br />
Note that if your page is served using HTTPS, you will also need to use https to retrieve the map, otherwise users will receive messages warning about mixed and unprotected content on the page:<br />
<br />
<iframe src="<strong>https</strong>://map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
Firefox version 23 (and presumably later) actually blocks such content entirely if http is used in the iframe src when embedding in an https page.<br />
<br />
If you can serve the same pages using either protocol, you can arrange for the map to serve using the same protocol as the page in which it is embedded by omitting the protocol, just starting with the two slashes, thus:<br />
<br />
<iframe src="<strong>//</strong>map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress or Falcon), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>http://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>http://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed for the University Map is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]http://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access, <br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=705
The Embedding API
2016-07-25T11:38:10Z
<p>dje39: /* Falcon */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>http://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>http://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
===HTTPS===<br />
<br />
Note that if your page is served using HTTPS, you will also need to use https to retrieve the map, otherwise users will receive messages warning about mixed and unprotected content on the page:<br />
<br />
<iframe src="<strong>https</strong>://map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
Firefox version 23 (and presumably later) actually blocks such content entirely if http is used in the iframe src when embedding in an https page.<br />
<br />
If you can serve the same pages using either protocol, you can arrange for the map to serve using the same protocol as the page in which it is embedded by omitting the protocol, just starting with the two slashes, thus:<br />
<br />
<iframe src="<strong>//</strong>map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>http://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>http://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed for the University Map is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]http://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access, <br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=704
The Embedding API
2016-07-25T11:37:48Z
<p>dje39: /* Falcon */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>http://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>http://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
===HTTPS===<br />
<br />
Note that if your page is served using HTTPS, you will also need to use https to retrieve the map, otherwise users will receive messages warning about mixed and unprotected content on the page:<br />
<br />
<iframe src="<strong>https</strong>://map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
Firefox version 23 (and presumably later) actually blocks such content entirely if http is used in the iframe src when embedding in an https page.<br />
<br />
If you can serve the same pages using either protocol, you can arrange for the map to serve using the same protocol as the page in which it is embedded by omitting the protocol, just starting with the two slashes, thus:<br />
<br />
<iframe src="<strong>//</strong>map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>http://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>http://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed is available as standard in the University's [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]http://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access, <br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Embedding_API&diff=703
The Embedding API
2016-07-25T11:37:26Z
<p>dje39: /* Falcon */</p>
<hr />
<div>Adding a small amount of HTML to your web pages allows you to embed a live version of the map in your own site.<br />
<br />
==IFRAME (manually embedding the map)==<br />
<br />
To embed a map in another web page, simply use an IFRAME, like this:<br />
<br />
<iframe src=''url''>(non-iframe text)</iframe><br />
<br />
where ''url'' is a standard map linking URL - see [[The Map URL API]]. For example:<br />
<br />
<iframe src="<nowiki>http://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>"></iframe><br />
<br />
Typically your CSS will set the width and height of the IFRAME, though you can also do this directly:<br />
<br />
<iframe src="<nowiki>http://map.cam.ac.uk/Lucy+Cavendish+College</nowiki>" style="width: 400px; height: 400px;"></iframe><br />
<br />
The presentation is slightly different from the full page for the same URL in that only the map is displayed without any ancillary information, titling, branding etc. The height and/or width of the iframe can be specified relative to the height/width of its containing elements (e.g. "width: 100%"). If the containing element changes size, as is common in responsive design, the map will adapt to the new size.<br />
<br />
We suggest not using the bounding box or ref form of URL for embedding a map relevant to an institution. By using the simple name of the institution or its code, then&nbsp;the map will<br />
* adjust if the institution moves (using &nbsp;a bounding box or building reference leaves it showing the old geographical location)<br />
* centre on the institution concerned&nbsp;<br />
* show a marker for just the institution concerned, not all of its neighbbours<br />
<br />
<br />
The src link can include an [[Map_Annotation|annotation overlay]] or positioning fragment.<br />
<br />
===HTTPS===<br />
<br />
Note that if your page is served using HTTPS, you will also need to use https to retrieve the map, otherwise users will receive messages warning about mixed and unprotected content on the page:<br />
<br />
<iframe src="<strong>https</strong>://map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
Firefox version 23 (and presumably later) actually blocks such content entirely if http is used in the iframe src when embedding in an https page.<br />
<br />
If you can serve the same pages using either protocol, you can arrange for the map to serve using the same protocol as the page in which it is embedded by omitting the protocol, just starting with the two slashes, thus:<br />
<br />
<iframe src="<strong>//</strong>map.cam.ac.uk/Lucy+Cavendish+College"></iframe><br />
<br />
==oEmbed (automatically recognising a map URL)==<br />
<br />
===What is oEmbed?===<br />
<br />
[http://oembed.com/ oEmbed] is a protocol which enables a content management system (such as Wordpress), to recognise a URL representing a resource (such as a video, or in our case a section of the University map) on a remote web site (such as YouTube or in our case the University map) and replace it with HTML which presents the resource directly instead of the link to it.<br />
<br />
In this way, an author of an article can just copy the URL for the resource and include it in their article. The system does the rest.<br />
<br />
Most CMSs that understand oEmbed come with some URLs built-in for widely known services, like YouTube. For others, such as the University Map, you have to tell the system about the additional URLs it should recognise. How this is done differs between systems.<br />
<br />
===Basic information===<br />
<br />
Each oEmbed provider comprises two pieces of information which you need to tell the CMS about, the ''URL scheme'' and the ''API endpoint''. The first is a pattern of URLs which the CMS will recognise for substitution and the second is a URL from which it can obtain the corresponding HTML to substitute. See [http://oembed.com/ the oEmbed specification] if you want more details about what these terms mean; usually you'll just need to put the information below in the place needed by your CMS.<br />
<br />
For the University map, these two are:<br />
* URL scheme: '''<nowiki>http://map.cam.ac.uk/*</nowiki>'''<br />
* API endpoint: '''<nowiki>http://map.cam.ac.uk/oembed/</nowiki>'''<br />
<br />
Providing these to a compliant CMS will then allow your authors to include URLs such as<br />
<br />
<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki><br />
<br />
in their articles and have them substituted with the corresponding live map. Obtain these URLs from the address bar in the browser after you have done the relevant search in the map (or from the Link to Map button). You can also include markers, overlaid annotation etc in these URLs.<br />
<br />
===Falcon===<br />
<br />
oEmbed is also available in the [http://falcon-help.csx.cam.ac.uk/ Falcon Content Management Service]. See Falcon's [http://falcon-help.csx.cam.ac.uk/content/complex-content/video page about embedding] for further information.<br />
<br />
===Wordpress===<br />
<br />
You can add knowledge of University Map URLs to Wordpress in two ways:<br />
<br />
* by installing a plugin, provided below.<br />
* programatically, as a PHP function call in the file ''functions.php'' for the theme you are using<br />
<br />
Quoting a map URL will then automatically include an <nowiki><iframe></nowiki> as above.<br />
<br />
If you want to control the size rather than taking the default Wordpress gives you, enclose the URL in an [http://codex.wordpress.org/Embeds <nowiki>[embed]</nowiki> shortcode], quoting the size, like this:<br />
<br />
<nowiki>[embed width="400" height="300"]http://map.cam.ac.uk/Department+of+Geography[/embed]</nowiki><br />
<br />
====Plugin====<br />
<br />
* Download the plugin from http://map.cam.ac.uk/oembed/ucammapoembed.zip <br />
* If you have Wordpress installed on a server where the dashboard has permission to write to your files:<br />
** install it using '''Add&nbsp;New''' at the top of the Plugins page in the control panel;<br />
** identify the zip file when asked;<br />
** then activate the plugin.<br />
* If you don't have dashboard access, <br />
** upload the zip file to the wp-content/plugins directory in your Wordpress installation;<br />
** unzip it on the server;<br />
** delete the zip file from the server;<br />
** go to the Plugins page on the Wordpress dashboard and activate the plugin.<br />
* Alternatively, if you can't unzip on the server, <br />
** first unzip the zip file you downloaded, and then <br />
** upload the unzipped files (they are small).<br />
(Uploading will usually be via SCP, SFTP or FTP or a server control panel such as cPanel).<br />
<br />
====PHP====<br />
<br />
The relevant Wordpress function is [http://codex.wordpress.org/Function_Reference/wp_oembed_add_provider wp_oembed_add_provider].<br />
<br />
Add it to your theme code like this:<br />
<br />
<nowiki><br />
function ucammapoembed_handler() {<br />
wp_oembed_add_provider('http://map.cam.ac.uk/*', 'http://map.cam.ac.uk/oembed/');<br />
}<br />
add_action( 'init', 'ucammapoembed_handler' );<br />
</nowiki></div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=702
UCamGeoJSON
2016-06-20T13:27:05Z
<p>dje39: /* Markers */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>http://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>http://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>http://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='http://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='http://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>http://map.cam.ac.uk/#z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling-red.png<br/>pling-green.png<br/>pling-blue.png<br/>pling-orange.png<br/>pling-yellow.png<br/>pling-purple.png<br/> || [[File:Pling.png]] || a pointer style icon in the colour indicated. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>http://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
http://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [http://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[http://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that CORS is relatively new technology. It requires the user's browser to support CORS. Most browsers do, but notably the still widely used Internet Explorer 8 (and earlier) does not. That means you probably have to know your users.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter, which means making two attempts, but will work in most instances. However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>http://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=UCamGeoJSON&diff=701
UCamGeoJSON
2016-06-20T13:20:40Z
<p>dje39: /* Using UCamGeoJSON */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
You can annotate and overlay the University Map with your own information. Typically you would draw on the map using the [http://map.cam.ac.uk/overlay Annotate Map web app] (Annotate map on the More menu) - [[Map_Annotation|see the documentation]] - but for those who want to derive overlays programmatically from existing data or otherwise roll their own, this describes how.<br />
<br />
'''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: ''<nowiki>http://map.cam.ac.uk/Department+of+Geography</nowiki>'' . This also means if you move, the link will show up-to-date information without any changes.<br />
<br />
Also, you can obtain a URL of the current map view, drop a custom marker onto the map and get a URL which includes that, from the map itself. See the [http://map.cam.ac.uk/help help page].<br />
<br />
==GeoJSON==<br />
<br />
Overlays are specified using UCamGeoJSON, a file format based on [http://www.geojson.org GeoJSON] (see [http://www.geojson.org/geojson-spec.html specification]), which in turn is based on the [http://en.wikipedia.org/wiki/JSON JSON] file format. UCamGeoJSON differs in three respects from GeoJSON:<br />
<br />
* It does not implement [http://www.geojson.org/geojson-spec.html#coordinate-reference-system-objects Co-ordinate Reference Systems]. All points are given as latitude and longitude using the WGS84 datum.<br />
<br />
* While GeoJSON only provides geometry, UCamGeoJSON defines the recognized content of the [[#Properties|'''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.<br />
<br />
* Additional members of the top level JSON object (e.g. '''pos''') can be given, to set the initial view of the map. See [[UCamGeoJSON#Initial_map_view|Initial map view]] below.<br />
<br />
Note that in JSON, unlike the somewhat more relaxed syntax for Javascript objects, key values must be included in double quotes, and comments are not permitted.<br />
<br />
==Using UCamGeoJSON==<br />
<br />
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:<br />
<br />
<nowiki>http://map.cam.ac.uk/...#data</nowiki><br />
<br />
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 [http://bit.ly bit.ly].<br />
<br />
The data can be included in one of three ways:<br />
<br />
* 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 '<nowiki>http://</nowiki>', but in many cases it will be relative to the map itself, and therefore start with a '/' (see especially [[#Adapters|Adapters]] below). For example:<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://www.example.com/my-ucamgeojson.json</nowiki><br />
<nowiki>http://map.cam.ac.uk/#/annotate/adapters/osm.json?src=http://www.example.com/my-osmfile.osm</nowiki><br />
<br />
:Do [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] these embedded URLs properly, but don't double escape them.<br />
<br />
:You can also abbreviate the full URLs of files stored on the map server itself (usually by the Annotate Map web app), jut to their assigned identifier, like this:<br />
<br />
<nowiki>http://map.cam.ac.uk/#YA45-YH8G-4VT4</nowiki><br />
<br />
:which is short for <br />
<br />
<nowiki>http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/get.json?id=YA45-YH8G-4VT4</nowiki><br />
<br />
:'''If your URL does not refer to the University's map server''', you will have to consider [[#Cross-site_scripting|cross site scripting restrictions]] otherwise your file may not be accessible to the map.<br />
<br />
* Sending the UCamGeoJSON data via a HTTP POST. This allows you to embed larger JSON data directly in a web page (in a form) and submit it on a user's action. This could be a 'submit' button, or you could hide the form and use Javascript's form.submit() to send it by clicking a link. In this case, set the hash fragment to 'annotate' and use the name 'annotation' as the POST variable. Note particularly the fragment (hash) part of the Map URL addressed by the form is ''#annotation'' For example:<br />
<br />
<nowiki><br />
<form action='http://map.cam.ac.uk/#annotate' method='POST'><br />
<input type='hidden' name='annotation'<br />
value='{"type":"Feature","geometry":{...},"properties":{...}}'/><br />
<input type='submit' value='Go To Map'/><br />
</form><br />
</nowiki><br />
<br />
If you want to embed the map in the same page where you have the annotation to hand, you can use the same API with a hidden form. The key to this is to use a ''target'' form attribute which is the name of an IFRAME. Submit the form using JavaScript. (Typically your annotation JSON would be substituted by the script creating the page, and would require escaping for special HTML characters when used with a TEXTAREA like this, but shown inline here for illustration):<br />
<br />
<nowiki><br />
<form id='myform' action='http://map.cam.ac.uk/#annotate' method='POST' target='myiframe'<br />
style='display: none;'><br />
<textarea name='annotation'>{"type":"Feature","geometry":{...},"properties":{...}}</textarea><br />
</form><br />
<iframe name='myiframe' style='width: 600px; height: 400px'></iframe><br />
<script>document.getElementById("myform").submit();</script><br />
<!-- or using jQuery: $("#myform").submit; --><br />
</nowiki><br />
<br />
* Giving numbers after the '#', separated by commas, thus:<br />
<br />
<nowiki>http://map.cam.ac.uk/#z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,mlat,mlon</nowiki><br />
<nowiki>http://map.cam.ac.uk/#lat,lon,z,mlat,mlon</nowiki><br />
<br />
:where ''lat,lon'' are the latititude and longitude of the centre of the map view, ''z'' is the zoom level (between 13 and 19) and ''mlat,mlon'' are the latitude and longitude of the tip of a default marker. There is no need to [http://en.wikipedia.org/wiki/Percent-encoding percent-escape] any of the numbers or commas.<br />
<br />
:These are equivalent to files containing the following (respectively):<br />
<br />
<nowiki>{"z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, feature}}</nowiki><br />
<nowiki>{"pos":{"type":"Point","coordinates":[lon,lat]}, "z":z, feature}}</nowiki><br />
<br />
:where ''feature'' represents the marker, for example:<br />
<br />
<nowiki><br />
{"type":"Feature",<br />
"geometry":{"type":"Point","coordinates":[mlon,mlat]},<br />
"properties":{"src":"/annotate/markers/pling.png"},"top":"-40px","left":"-13px"}<br />
</nowiki><br />
<br />
Further pairs of numbers represent additional markers. You can have any reasonable number of markers, but there are only six distinct colours which will be repeated if you ask for more than six markers.<br />
<br />
==Initial map view==<br />
<br />
The top level GeoJSON object may additionally contain some or all of the members '''z''', '''pos''', '''expand''', '''nearby''' and '''title''' 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.<br />
<br />
* '''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.<br />
<br />
* '''pos''' is the point on which the map is initial centred. The value of pos is a [http://www.geojson.org/geojson-spec.html#point GeoJSON Point object], that is it provides a latitude and longitude on which the map is to be centred.<br />
<br />
* '''nearby''' is either a boolean value or a GeoJSON Point object. If a Point object, this causes the map to display institutions near to the Point. If '''true''', then '''pos''' (which must be present) is used as the point. This is equivalent to the user choosing the 'show nearby' function on the relevant point on the map before the annotation is displayed.<br />
<br />
* '''title''' is a text heading that will be placed in the map's information panel, to title the page. This is text, encoded in UTF-8, and not HTML.<br />
<br />
* '''bodytext''' is text to appear below the '''title''' in the map's information panel.<br />
<br />
For example:<br />
<br />
{ "pos": {"type":"Point", "coordinates":[52.2036,0.1202]},<br />
"z": 19,<br />
"nearby": true,<br />
"type": "FeatureCollection",<br />
"features": [...] }<br />
<br />
==Properties==<br />
<br />
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.<br />
<br />
UCamGeoJSON does define '''properties''', as follows. In general the properties are a subset of CSS and SVG, so the detailed formats of each need not be defined here, only any special interpretation of them. Refer to CSS and SVG for the details. Many of these are indeed simply applied as CSS styles and SVG attributes to the graphic objects created in the HTML DOM.<br />
<br />
In broad terms, the geometry provides filled areas, lines and points. <br />
<br />
Areas and lines are drawn by applying a few styling properties, such as '''color''' (note US spelling, as in CSS). <br />
<br />
Points are represented by icons (indeed any 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 '''<em>the box</em>'''), which allows for flexible and controllable layout using CSS.<br />
<br />
===properties applied to filled shapes and lines===<br />
<br />
Namely: shapes as GeoJSON Polygon and MultiPolygon objects and lines as LineString and MultiLineString objects.<br />
<br />
Note: line and outline widths are in pixels at whatever zoom level they are displayed. The width of a line is invariant and does not scale according to the zoom level.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''filled shapes''' || '''lines''' || '''notes'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour with which the shape is filled<br />
| colour in which the line is drawn (note: '''stroke-color''' overrides this)<br />
| any CSS colour specification is allowed, e.g. a name like 'green', hash and six hex digits, or 'rgb(...)' etc. Default is '''tomato''' (a bright-ish red). Note US spelling of ''color''.<br />
|-<br />
| stroke-width<br />
| the width in pixels of the outline drawn around the shape. If not given, or zero, '''no outline is drawn'''.<br />
| the width in pixels of the line<br />
| <br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the filled shape (and the outline, if '''stroke-opacity''' is not given separately).<br />
| of the line (note: ignored if '''stroke-opacity''' also given).<br />
| <br />
|-<br />
| stroke-color<br />
| colour of outline<br />
| colour of the line<br />
| <br />
|-<br />
| stroke-opacity<br />
| the opacity of outline<br />
| the opacity of the line<br />
| a number between zero and one e.g. '''0.5'''. If not given, '''opacity''' is used in both cases (so if you just give opacity it applies to both the filled shape and its outline).<br />
|-<br />
| stroke-linecap,<br/>stroke-linejoin,<br/>stroke-miterlimit<br />
| specialized properties for outline<br />
| specialized properties for line<br />
| see [http://www.w3.org/TR/SVG/painting.html#StrokeProperties the SVG specification] for details of these<br />
|-<br />
| <span style='white-space: nowrap;'>stroke-dasharray</span><br />
| dash pattern for outline<br />
| dash pattern of line<br />
| a string, one of<br />"'''-'''", "'''.'''", "'''-.'''", "'''-..'''", "'''.''' ", "'''-''' ", "'''--'''", "'''- .'''", "'''--.'''", "'''--..'''"<br />forming a mixture of dashes and dots accordingly. Note that this is not the same as the SVG property stroke-dasharray, but derives from the cross-browser [http://raphaeljs.com/ Raphaël] system ([http://raphaeljs.com/reference.html#Element.attr documentation]).<br />
|}<br />
<br />
===properties applied to both text and images===<br />
<br />
Namely, GeoJSON Point and MultiPoint objects.<br />
<br />
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. <br />
<br />
The same content (typically several marker icons) is displayed for each point in a MultiPoint.<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/background background], <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/background-color background-color]</span><br />
| the background of the box. Default is transparent.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border border],<br /><span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-color border-color]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-width border-width]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-left border-left]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-right border-right]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-top border-top]</span>, <span style='white-space: nowrap;'>[http://developer.mozilla.org/en-US/docs/CSS/border-bottom border-bottom]</span><br />
| 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.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/border-radius border-radius]<br />
| of the box. Rounded corners don't work in older browsers.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/opacity opacity]<br />
| of the background of the box<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/width width], [http://developer.mozilla.org/en-US/docs/CSS/height height]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''10px''', not just 10.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/overflow overflow]<br />
| of the box contents, defaults to '''hidden''' if '''height''' is also given.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href href]<br />
| a URL: the whole of the box content will link to the given URL.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target target]<br />
| The name of the target window in the browser in which the link referenced by '''href''' should be opened. By default this is the page in which the map is displayed or embedded (in an iframe), that is, equivalent to '''_self''' for the ordinary map or '''_top''' when embedded in an iframe. To make the link also open inside the iframe, you need to specify '''_self''' for target. In either case, to open in a new window or tab use '''_blank'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/top top], [http://developer.mozilla.org/en-US/docs/CSS/left left]<br />
| 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. Note: the CSS unit "px" must be included, e.g. '''-20px''', not just -20. Typically, these will be minus half the width and height, though for an arrow, for example, they might offset to the tip of the arrowhead.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/padding padding]<br />
| around the inside of the box (pixels only)<br />
|}<br />
<br />
===properties applied to images/icons/markers===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| src<br />
| 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! A JPG might be appropriate if you are displaying a thumbnail portrait, for example.<br/> A few [[UCamGeoJSON#Markers|ready made icons and markers]] are provided at http://map.cam.ac.uk/annotate/markers, though you can, of course, use any image accessible via http.<br />
|-<br />
| title<br />
| the title attribute of the image (usually displayed by browsers in a 'tool tip' when hovering over it.<br />
|-<br />
| img-width, img-height<br />
| width and height applied to the image including the 'px' unit (remember, '''width''' and '''height''' apply to the containing box). e.g '''40px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/float float]<br />
| '''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<br />
|-<br />
| br<br />
| if there is both image and text, values of '''above''' or '''below''' insert a newline between image and text and position the image above or below the text, respectively. (Actually, any non-empty value is equivalent to '''above''').<br />
|}<br />
<br />
===properties applied to text===<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| '''property name''' || '''meaning'''<br />
|-<br />
| content<br />
| 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 &lt;br/&gt;). You can write a newline in JSON with backslash-n: "...\n...". You can also cause strings to wrap if you use the width property, but where the break occurs is then not easily predictable.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/color color]<br />
| colour of the text; any CSS colour specification is allowed, e.g. a name like '''green''', '''#ccaa12''', or '''rgb(12,128,44)''' etc. Default is '''black'''.<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-family font-family]<br />
| Just because you have a particular font installed on your computer doesn't mean the recipient has - so use web-safe fonts, e.g. Verdana, Tahoma, Trebuchet, Georgia, Times, Helvetica<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-size font-size]<br />
| in pixels only, e.g. '''12px'''<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/font-weight font-weight], [http://developer.mozilla.org/en-US/docs/CSS/font-style font-style], [http://developer.mozilla.org/en-US/docs/CSS/text-decoration text-decoration], [http://developer.mozilla.org/en-US/docs/CSS/letter-spacing letter-spacing], [http://developer.mozilla.org/en-US/docs/CSS/word-spacing word-spacing], [http://developer.mozilla.org/en-US/docs/CSS/lne-height line-height]<br />
| per CSS<br />
|-<br />
| [http://developer.mozilla.org/en-US/docs/CSS/text-align text-align]<br />
| '''center''' (US spelling), '''left''', '''right''' within the box. This will also apply to any image which isn't floated.<br />
|}<br />
<br />
==Markers==<br />
<br />
Ready-made markers are available for use with the '''src''' property, as follows. These are located in /annotate/markers, hence you might write:<br />
"src": "/annotate/markers/circle-r.png"<br />
<br />
{| class="wikitable" cellpadding="5"<br />
| ring.png || [[File:Circle.png]] || a 40px diameter open red circle on a transparent background<br />
|-<br />
| rect.png || [[File:Rect.png]] || a 40px open red square on a transparent background<br />
|-<br />
| circle-r.png<br/>circle-b.png<br/>circle-g.png || [[File:Circle2.png]] || a 40px diameter solid red circle on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| block-r.png<br/>block-b.png<br/>block-g.png || [[File:Block.png]] || a 40px solid red square on a transparent background with -r suffix. Also in blue and green (-b and -g suffixes)<br />
|-<br />
| pling.png || [[File:Pling.png]] || a pointer style icon. Note: use '''"top":"-40px","left":"-13px"''' to have marker tip at the identified point<br />
|-<br />
| arrowNNN.png || e.g. arrow045.png [[File:Arrow045.png]] || a set of 72 markers, each 80px across, with red arrows arranged pointing in to the centre at 5 degree intervals. NNN is a three digit number representing the angle in degrees (with leading zeros) of the arrow, where zero is pointing west (that is, the arrow occupies the positive x-axis) and increases anti-clockwise. So for example an arrow pointing from NE to SW is at 45 degrees and is '''arrow045.png'''. That arrow is 40px long and occupies the top right portion of the 80px square.<br />
|}<br />
<br />
==Adapters==<br />
<br />
Though the map understands UCamGeoJSON, certain other formats can be managed using adapters. These are scripts which dynamically convert data (identified via their query strings etc) into UCamGeoJSON.<br />
<br />
Some default scripts are provided at <nowiki>http://map.cam.ac.uk/annotate/adapters</nowiki>:<br />
<br />
* 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.<br />
<br />
* GBN: '''gbn.json'''. Reads the OpenStreetMap XML file containing Granta Backbone network description. This operation requires appropriate privileges. For example:<br />
<br />
http://map.cam.ac.uk/#http://annotate.map.cam.ac.uk/adapters/gbn.json<br />
<br />
* College staircases, '''staircases.json'''. For example, for Pembroke College:<br />
<br />
http://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
Other useful candidates would be: KML, GPX.<br />
<br />
Of course, as the URL for UCamGeoJSON content is arbitrary, it is possible to provide other adapters on any web site.<br />
<br />
==URL referencing considerations==<br />
<br />
===Cross-site scripting===<br />
<br />
If you use a URL to access JSON data and that URL indicates somewhere other than the University's map server, you have to consider ''cross site scripting'' restrictions.<br />
<br />
In general, a web page from one server cannot request data from another, for [http://en.wikipedia.org/wiki/Same_origin_policy security reasons]. This means you will get an error if you naïvely use a non-map URL after the hash.<br />
<br />
There are several ways in which this can be worked around.<br />
<br />
* '''Use ''[http://en.wikipedia.org/wiki/Cross-origin_resource_sharing CORS]'''''. You need access to the web site files for the server providing the data for this to work. The server on which the data is stored responds with some additional information which says it is OK for the map to use the data. For Apache servers, (at least) the following can be put in a .htaccess file in the directory where the data is being retrieved from (whether the data is static file or scripted). This depends on the web server allowing these options to be set in .htaccess.<br />
<br />
Header add Access-Control-Allow-Origin "*"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
<br />
:If you want to restrict the data only to the map, use ''<nowiki>http://map.cam.ac.uk</nowiki>'' instead of the asterisk in the first line (the asterisk means you are giving permission to any requesting page). Note that when using Desktop Services [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] service these lines need to appear in a file called 'htaccess', not '.htaccess'.<br />
<br />
* '''Use a site that already has ''CORS'' turned on for you'''. That is, a storage provider who recognises that the data will be required by other sites. In this case you need do nothing, the request should just work.<br />
<br />
:'''However''', note that CORS is relatively new technology. It requires the user's browser to support CORS. Most browsers do, but notably the still widely used Internet Explorer 8 (and earlier) does not. That means you probably have to know your users.<br />
<br />
* '''Let the map sort it out'''. If the map is unable to fetch the JSON, it will then automatically try to fetch is using its CORS adapter, which means making two attempts, but will work in most instances. However, this does not work with password protected sites, because even though you may have logged in, it is the map server asking for the data, not your own browser, so you will not be logged in: see below.<br />
<br />
* '''Use the CORS adapter''' explicitly, if you know ahead of time that CORS is not supported by the supplying server: <br />
<br />
...#/annotate/adapters/cors.json?url=''your-url-here''<br />
<br />
:This will bypass the first request by the browser for the bald URL, which is bound to fail if you know your server does not support CORS. This has the effect of asking the map server to retrieve your file for you. However the same caveat for login protected sites also applies, of course.<br />
<br />
===Login-protected sources===<br />
<br />
Sometimes overlays may be located on sites which require a login, especially when these are confidential.<br />
<br />
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 (with the necessary CORS headers - see below). Just put '''?raw=1''' on the end of the Dropbox URL so it gives the original file not their preview page for the file.<br />
<br />
Where a resource is [https://raven.cam.ac.uk/ Raven] protected (perhaps further restricted to a particular [http://www.lookup.cam.ac.uk/group 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.<br />
<br />
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.<br />
<br />
However, this can only work when<br />
* the client's browser supports CORS - which means users working with protected data cannot be using Internet Explorer 8 or earlier - and<br />
* the file or adapter which supplies the data must supply more specific CORS headers, either in .htaccess as follows, or the equivalent form your script (e.g. using header(...) in PHP).<br />
<br />
Header add Access-Control-Allow-Origin "<nowiki>http://map.cam.ac.uk</nowiki>"<br />
Header add Access-Control-Allow-Headers "origin, x-requested-with, content-type"<br />
Header add Access-Control-Allow-Methods "GET"<br />
Header add Access-Control-Allow-Credentials: true<br />
<br />
This allows the map to access your server, and include the login cookie with the request. But the Access-Control-Allow-Origin header must then be a specific URL, not the wildcard '*' as in the earlier example, because browser security restrictions require this when cookies are supplied.<br />
<br />
Similar considerations apply to non-University sites which are protected by a login controlled by a cookie.<br />
<br />
The consequence of this is that it is not possible to support login protected annotations for users whose browsers do not support CORS.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=699
Map Annotation
2016-01-19T14:34:38Z
<p>dje39: /* How? */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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.<br />
<br />
Also if you only want a single pin on the map, you can do this directly from the map: click where you want it and choose the pin icon. Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (Raven login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [http://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>http://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
http://map.cam.ac.uk/#http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[http://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link & Hover Text====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mid some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=695
Map Annotation
2015-08-13T18:16:35Z
<p>dje39: /* Saving in the cloud */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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.<br />
<br />
Also if you only want a single pin on the map, you can do this directly from the map: click where you want it and choose the pin icon. Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (Raven login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [http://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
Note that at present there's only support for displaying annotated maps on screens. In particular there's no way of creating copies of annotations suitable for high-quality printing. Screen grabs could be used to do this, but the results are unlikely to be satisfactory.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>http://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
http://map.cam.ac.uk/#http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[http://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link & Hover Text====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mid some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39
https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=694
Map Annotation
2015-08-13T18:13:47Z
<p>dje39: /* Saving in the cloud */</p>
<hr />
<div>Please read [[Terms and conditions, Copyright, Fair Use, etc.]] if you are going to use the facilities described here.<br />
<br />
==Introduction==<br />
<br />
This page provides information about interactive annotation of the University Map.<br />
<br />
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.<br />
<br />
Also if you only want a single pin on the map, you can do this directly from the map: click where you want it and choose the pin icon. Then copy the URL from the browser address bar.<br />
<br />
If you are interested in scripting or programming overlays from other data sets, see [[UCamGeoJSON|the UCamGeoJSON API]].<br />
<br />
This page deals with more substantial annotations, produced interactively.<br />
<br />
===Why?===<br />
<br />
It is useful to be able to customize the University Map. This might be for<br />
* something ephemeral, like emailing directions or highlighting a meeting place to someone;<br />
* something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);<br />
* something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).<br />
<br />
===Where?===<br />
<br />
This is achieved by referencing in the map URL a set of annotations stored at a another URL somewhere on the internet. This could be <br />
* storage provided by the map server itself (Raven login required), <br />
* your personal University web pages, <br />
* a departmental website, <br />
* a shared Dropbox file (or other cloud service)<br />
* anywhere, really, subject to certain security limitations<br />
<br />
This URL is given in the ''fragment'' part of the map URL, that is, the bit after a hash sign '#', like this<br />
<br />
<nowiki>http://map.cam.ac.uk/#http://some.annotations.com/annotation1.json</nowiki><br />
<br />
===How?===<br />
<br />
The link provides a set of data in [[UCamGeoJSON|UCamGeoJSON format]]. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use [http://map.cam.ac.uk/overlay interactive Map Annotation], in effect to draw on top of the map and then save your annotations for other people to refer to.<br />
<br />
Note that at present there's only support for displaying annotated maps on screens. In particular there's no way of creating copies of annotations suitable for high-quality printing. Screen grabs could be used to do this, but the results are unlikely to be satisfactory.<br />
<br />
==Getting started==<br />
<br />
''Annotate the map'' on the ''More'' link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.<br />
<br />
A set of annotations comprises one or more ''features'', which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: ''points'' (to which images and text can be attached), ''lines'' and ''areas''.<br />
<br />
Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.<br />
<br />
==Adding points, lines and areas==<br />
<br />
If you make a mistake at any time, you can use the ''Undo'' button (or the CTRL+Z key) to reverse your change. ''Redo'' on the ''Data'' menu reverses Undo.<br />
<br />
Click on the map to make a point. This is shown with a small green or red mark called a ''handle''. <br />
<br />
A red handle indicates that it is ''selected'', that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using ''Select All'' and de-select everything with ''Select None'' on the ''Features'' menu.<br />
<br />
Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.<br />
<br />
To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.<br />
<br />
Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.<br />
<br />
If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.<br />
<br />
Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.<br />
<br />
==Changing existing features==<br />
<br />
Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.<br />
<br />
You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).<br />
<br />
The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.<br />
<br />
===Features===<br />
<br />
* ''Delete feature'' deletes all the features containing selected points.<br />
<br />
* ''Bring to front'' and ''Send to back'' change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).<br />
<br />
* ''Duplicate feature'' to make a copy of the features containing selected points, slightly offset from the originals<br />
<br />
* To start over with no features, use ''Clear all'' on the ''Data'' menu. (If you accidentally delete everything with this, you can ''Undo'' it).<br />
<br />
* ''Select all'' selects the first handle of all features.<br />
<br />
* ''Select none'' deselects all selected handles.<br />
<br />
===Points===<br />
<br />
* ''Insert point'' adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.<br />
<br />
:You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.<br />
<br />
* ''Remove point'' removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.<br />
<br />
* ''Make horizontal'' and ''Make vertical'' align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.<br />
<br />
==Saving and Loading==<br />
<br />
===Save features===<br />
<br />
When you have completed your annotation, you'll want to do something with it. Use ''Save features'' on the ''Data'' menu to do this.<br />
<br />
There are two ways you can save your data:<br />
<br />
* Store it on the map's server under your University Raven user account. Data saved in this way can be updated from the same account in the future without the link changing.<br />
<br />
* Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.<br />
<br />
If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.<br />
<br />
====Saving in your personal University webspace====<br />
<br />
University users with a [http://www.ucs.cam.ac.uk/desktop-services/mcs Desktop Services 'Managed Cluster Service'] (MCS) account have a personal [http://www.ucs.cam.ac.uk/desktop-services/ds-web DS-Web] web site available to them where they can put files accessible to anyone. This is located in a folder called '''public_html''' in your [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore DS-Filestore central file storage]. That in turn can be accessed from a MCS workstation, from a MCS Linux server, via SFTP to sftp.ds.cam.ac.uk, or using the [http://www.ucs.cam.ac.uk/desktop-services/ds-filestore/dsfiles DS-Files web interface] at https://dsfiles.ds.cam.ac.uk/. Under some circumstances it's also possible to mount your MCS filespace on another computer where it will look look like a drive letter on a PC. <br />
<br />
So, once you have created your annotation, use Save Features with the Download File option. If you are working on a MCS workstation or have otherwise mounted your DS-Filestore area, you can save it directly to your public_html directory. If not, save it to a file on your computer, and then upload it using SFTP, the web interface, or otherwise. The link to the file will be <nowiki>http://people.ds.cam.ac.uk/''youruserid''/''yourfilename''</nowiki>, for example <br />
http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
and that means the link to overlay it on the map looks like this:<br />
http://map.cam.ac.uk/#http://people.ds.cam.ac.uk/dje39/2013-02-01-18-41.ucamgeo.json<br />
<br />
====Saving in the cloud====<br />
<br />
Non-university users, and those who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both<br />
* through a public, unprotected link, and<br />
* directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file<br />
<br />
[http://www.dropbox.com Dropbox] can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.<br />
<br />
====A note about protecting annotation overlays====<br />
<br />
Most overlays will be accessible by anyone who knows the link, and they will work just fine.<br />
<br />
However, if you want to make overlays available only to a limited group of people, you need to know a little more.<br />
<br />
A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using [[UCamGeoJSON#Cross-site_scripting|CORS]]. <br />
<br />
However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.<br />
<br />
If you are requiring a Raven login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so<br />
* you '''must''' implement provision of CORS headers with the overlays you serve<br />
* the Access-Control-Allow-Origin header '''may not''' use a wildcard for the permitted site: it must specify http://map.cam.ac.uk explicitly.<br />
* you '''must''' also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.<br />
* nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.<br />
<br />
===Load features===<br />
<br />
'''Load features''' on the '''Data''' menu does the opposite of ''Save''. You can load annotations from a URL or by pasting the contents of a file, and then amend them.<br />
<br />
If you load data originally saved permanently to the map server using your Raven account and identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).<br />
<br />
If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.<br />
<br />
Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.<br />
<br />
==Changing Appearance==<br />
<br />
Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.<br />
<br />
Click the subheadings in each section to set properties in that group.<br />
<br />
Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.<br />
<br />
===Heading===<br />
<br />
With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.<br />
<br />
Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.<br />
<br />
<div id='point-general'></div><br />
<br />
===Point style===<br />
<br />
The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).<br />
<br />
====Image/Icon====<br />
<br />
You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office. <br />
<br />
Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.<br />
<br />
You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.<br />
<br />
You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.<br />
<br />
====Text====<br />
<br />
Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.<br />
<br />
You can also adjust the font, size, colour, style, underlining and various spacings from this panel.<br />
<br />
====Layout====<br />
<br />
These settings control how the box, image and text are positioned in relation to each other.<br />
<br />
The offset of the top-left corner of the box will often be negative to move the box up and to the left.<br />
<br />
====Link & Hover Text====<br />
<br />
You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.<br />
<br />
Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.<br />
<br />
====Background====<br />
<br />
Choose the colour of the background of the box here, and whether it is partially transparent.<br />
<br />
Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.<br />
<br />
Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.<br />
<br />
====Border====<br />
<br />
You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.<br />
<br />
<div id='line-general'></div><br />
<br />
===Line style===<br />
<br />
====Colour and width====<br />
<br />
Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.<br />
<br />
Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.<br />
<br />
====Details====<br />
<br />
Your line can be partially transparent. You can also use dashes.<br />
<br />
<div id='fill-general'></div><br />
<br />
===Area style===<br />
<br />
====Fill====<br />
<br />
Set just the colour and transparency of the filled area here.<br />
<br />
====Outline====<br />
<br />
Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.<br />
<br />
Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.<br />
<br />
==Templates==<br />
<br />
Template annotations are ready made items which can be used to get a head start in preparing an overlay.<br />
<br />
Typically you would <br />
* go to Annotate the Map, <br />
* select Data > Load Features, <br />
* enter the template URL to bring the set of shapes defined by the template into your map<br />
* move them and modify them to suit your needs.<br />
<br />
===Pointers and labels===<br />
<br />
<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json</nowiki><br />
<br />
This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.<br />
<br />
For example<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30</nowiki><br/><br />
produces shapes 30 pixels across;<br/><br />
&nbsp;&nbsp;<nowiki>http://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue</nowiki><br/><br />
additionally colours them blue.<br />
<br />
If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.<br />
<br />
Query string options are as follows:<br />
<br />
start=N - N is first label number (1..99, default=1)<br />
end=N - N is last label number (1..99, >= start, default=25)<br />
size=N - N is width in pixels of the displayed pointer (heights depend on icon, <br />
but are usually more, default=25. This is not necessarily the same as <br />
the actual number of pixels in the image, which can be varied with <br />
resolution below, just the size it is displayed at).<br />
resolution=R - R in dots per inch, 72..300, default is a nominal screen resolution (a little <br />
over 90dpi) such that the size is the number of pixels both of the display and the image<br />
colour=C - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without<br />
the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato<br />
color=C - same as colour<br />
textcolour=C - C is colour of the text (default=white)<br />
textcolor=C - same as textcolour<br />
shape=S - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; <br />
default=plantpotrounded<br />
direction=D - D is one of the eight compass points indicating (where relevant) which direction the <br />
pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S<br />
<br />
Bear in mid some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.</div>
dje39