https://wiki.cam.ac.uk/wiki/university-map/api.php?action=feedcontributions&user=bjh21&feedformat=atomUniversity Map Wiki - User contributions [en]2024-03-29T12:48:58ZUser contributionsMediaWiki 1.39.4https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Main_Page&diff=752Main Page2024-03-22T16:34:18Z<p>bjh21: Updates service desk email</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 servicedesk@uis.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>bjh21https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=751Map Annotation2024-01-03T15:22:41Z<p>bjh21: /* A note about protecting annotation overlays */ Map uses HTTPS now</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 the cloud====<br />
<br />
Users 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 https://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>bjh21https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Map_Annotation&diff=750Map Annotation2024-01-03T15:17:20Z<p>bjh21: /* Saving and Loading */ Removed mention of DS-Web because it no longer exists</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 the cloud====<br />
<br />
Users 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>bjh21https://wiki.cam.ac.uk/wiki/university-map/index.php?title=Introduction_and_examples&diff=745Introduction and examples2021-09-20T17:50:40Z<p>bjh21: Replace webtools links with links to demo.map, new home of those files</p>
<hr />
<div>==Basic use==<br />
<br />
See [http://map.cam.ac.uk/help/ the Map's user help page] for further details.<br />
<br />
* The map 'frontpage': http://map.cam.ac.uk/. <br />
* You can search for most things and once you've found something you'll also get addresses and other contact details. <br />
* Clicking shows a popup menu that, among other things, lets you see what's nearby and can mark locations on the map.<br />
* The map automatically adapts for display on small-screen devices<br />
* Most views have individual URLs that can be copied and used elsewhere (on web pages, in emails, etc.)<br />
<br />
==API for linking to maps==<br />
<br />
The map exposes a URL for linking to particular views based on searches - see [[The Map URL API]] for details. For example:<br />
<br />
* http://map.cam.ac.uk/Computing+Service (location of the UCS)<br />
* http://map.cam.ac.uk/New+Museums+Site (location of the New Museums Site)<br />
* http://map.cam.ac.uk/saint (everything containing 'saint', multiple hits)<br />
* http://map.cam.ac.uk/saint%20johns%20street ('St John's Street', note lower case, 'saint' vs. 'st', omitted apostrophe, and %20 for space)<br />
<br />
There's an extended search syntax, for example:<br />
<br />
* http://map.cam.ac.uk/?q=dow&partial=partial (everything containing words starting 'dow')<br />
* http://map.cam.ac.uk/?q=saint&filter=college (all colleges with 'saint' in their names, but not roads or anything else)<br />
<br />
You can also produce links based on underlying ''geographic'' OSM identifiers, which are based on University Planon IDs where possible and which identify sites, buildings and entrances:<br />
<br />
* http://map.cam.ac.uk/?ref=M038 (The Austin Building - note that's a Planon ID)<br />
* http://map.cam.ac.uk/?ref=STEDMUNDS019 (St Edmund's building 019 - extended ID scheme for college buildings and those University buildings not covered by Planon)<br />
<br />
There's an [http://map.cam.ac.uk/refbrowser/ interactive browser] (also linked from the 'More...' menu) that you can use to explore the map's geographic database and to to help find these various identifiers.<br />
<br />
It's also possible to construct links based on institution identifiers, which in turn are based on the 'institution Identifiers' used in [http://www.lookup.cam.ac.uk Lookup]:<br />
<br />
* http://map.cam.ac.uk/?inst=CS (the UCS, by INSTID)<br />
<br />
If all else fails you can link to a physical areas:<br />
<br />
* http://map.cam.ac.uk/?bb=52.2043,0.11835,52.2025,0.1216 (New Museums Site)<br />
<br />
Map URLs can also have a fragment part consisting of a hash followed by further information. The fragment part comprises either one to five numbers, or another URL. The numbers control where the map is displayed initially - for example here's a map showing the Hopkinson Lecture Theatre but scaled and centred to also show the station:<br />
<br />
* http://map.cam.ac.uk/Hopkinson+Lecture+Theatre#52.199669,0.127349,15<br />
<br />
If the fragment is a URL it references an annotation overlay - see below. Further details of all this are available in [[The Map URL API]].<br />
<br />
==Embedding Maps==<br />
<br />
All map URL's can be used as the source for an iframe to simply embed the corresponding map in a seperate page - see [[The Embedding API]] for details. <br />
<br />
For example this:<br />
<br />
<!DOCTYPE html><br />
<html><br />
<br />
<head><br />
<title>Iframe test</title><br />
<style type="text/css"><br />
#map {<br />
width: 400px;<br />
height: 400px;<br />
border: 1px solid black;<br />
}<br />
</style><br />
</head><br />
<br />
<body> <br />
<br />
<iframe id="map" src="http://map.cam.ac.uk/Computing+Service"><br />
</iframe><br />
<br />
</body><br />
<br />
</html><br />
<br />
Produces [https://demo.map.cam.ac.uk/ucs-iframe.html a page like this].<br />
<br />
==Annotation==<br />
<br />
===Manual annotation===<br />
<br />
The map includes a tool to create and edit map overlays - see [[Map Annotation]] for details.<br />
<br />
The tool can be found at http://map.cam.ac.uk/overlay/ (also available from the 'Annotate the map' entry in the 'More...' menu). Points, lines, and areas can be drawn, modified, edited, styled. etc. Once complete, the annotation can be stored in the map system where each set of annotations gets its own permanent URL - e.g.:<br />
<br />
* http://map.cam.ac.uk/#YNKQ-N89P-ZMXP<br />
<br />
<br />
Alternatively it can be downloaded and served from any web server and then referenced after the hash part of a map URL, e.g.:<br />
<br />
* http://map.cam.ac.uk/#https://demo.map.cam.ac.uk/annotation.json<br />
<br />
===Annotation based on other data===<br />
<br />
Annotations can also be created programmaticly form other geographic data, either statically or on the fly, and then overlaid on the map. See [[UCamGeoJSON]] for details.<br />
<br />
For example, a static UCamGeoJSON file used to display the locations and identifier of all the Cambridge Colleges:<br />
<br />
* http://map.cam.ac.uk/#https://demo.map.cam.ac.uk/colleges/colleges.json<br />
<br />
Or a script that dynamically extracts staircase information direct from the OpenStreetMap database and displays it:<br />
<br />
* http://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM<br />
<br />
==Tile API==<br />
<br />
The tiles making up the map are freely available - see [[The Tile API]]. <br />
<br />
Here are [https://demo.map.cam.ac.uk/tiles.html some of the tiles that make up the city centre].<br />
<br />
They follow the conventions of OpenStreetMap and other similar systems and so can be consumed in various ways. Here are some examples using third-party map APIs:<br />
<br />
* [https://demo.map.cam.ac.uk/open-layers.html An example displaying our tiles, OSM's, or Google's] using [http://openlayers.org/ OpenLayers]. <br />
* [https://demo.map.cam.ac.uk/leaflet.html An example with marker and shape overlay] using [http://leafletjs.com/ Leaflet]<br />
* [https://demo.map.cam.ac.uk/google.html A further example combining our tiles and Google's], this time using [https://developers.google.com/maps/ the Google Maps API]<br />
<br />
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.<br />
<br />
==Index API==<br />
<br />
There's an API for accessing the data in the map's index - see [[The Database API]]. It uses similar queries to those used to draw and embed maps and returns results in JSON format. To ease experimentation you can add '&debug=1' to all index API queries to have results displayed in a browser rather than exported as JSON files. Here are some examples based on the map URLs above:<br />
<br />
* http://map.cam.ac.uk/v6.json?q=Computing+Service ([http://map.cam.ac.uk/v6.json?q=Computing+Service&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?q=New+Museums+Site ([http://map.cam.ac.uk/v6.json?q=New+Museums+Site&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?q=saint ([http://map.cam.ac.uk/v6.json?q=saint&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?q=saint%20johns%20street ([http://map.cam.ac.uk/v6.json?q=saint%20johns%20street&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?q=dow&partial=partial ([http://map.cam.ac.uk/v6.json?q=dow&partial=partial&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?q=saint&filter=college ([http://map.cam.ac.uk/v6.json?q=saint&filter=college&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?ref=M038 ([http://map.cam.ac.uk/v6.json?ref=M038&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?ref=STEDMUNDS019 ([http://map.cam.ac.uk/v6.json?ref=STEDMUNDS019&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?inst=CS ([http://map.cam.ac.uk/v6.json?inst=CS&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?bb=52.2021,0.1184,52.2047,0.1218 ([http://map.cam.ac.uk/v6.json?bb=52.2021,0.1184,52.2047,0.1218&debug=1 debug version])<br />
* http://map.cam.ac.uk/v6.json?alpha=a ([http://map.cam.ac.uk/v6.json?alpha=a&debug=1 debug version])<br />
<br />
The [http://map.cam.ac.uk/refbrowser/ interactive browser] (also linked from the 'More...' menu) can be useful for identifying the various codes in use.</div>bjh21https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Map_URL_API&diff=744The Map URL API2021-09-20T17:49:27Z<p>bjh21: Replace webtools links with links to demo.map, new home of those files</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/#https://demo.map.cam.ac.uk/annotation.json<br />
https://map.cam.ac.uk/#52.206397,0.114015,16,https://demo.map.cam.ac.uk/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>bjh21https://wiki.cam.ac.uk/wiki/university-map/index.php?title=The_Database_API&diff=698The Database API2015-11-12T16:51:14Z<p>bjh21: /* Coordinates */ Link to OSM API specs</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>http://map.cam.ac.uk/v6.json?</nowiki>q=''search''[&amp;partial=yes]<br />
<nowiki>http://map.cam.ac.uk/v6.json?</nowiki>bb=''boundingbox''<br />
<nowiki>http://map.cam.ac.uk/v6.json?</nowiki>ref=''ref''<br />
<nowiki>http://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>http://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>http://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 [http://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>http://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>bjh21