Difference between revisions of "Introduction and examples"

From University Map Wiki
Jump to navigationJump to search
(Created)
 
(Replace webtools links with links to demo.map, new home of those files)
 
(35 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
==Basic use==
 
==Basic use==
  
* The map 'fronpage': http://map.cam.ac.uk/
+
See [http://map.cam.ac.uk/help/ the Map's user help page] for further details.
 +
 
 +
* The map 'frontpage': http://map.cam.ac.uk/.
 +
* You can search for most things and once you've found something you'll also get addresses and other contact details.
 +
* Clicking shows a popup menu that, among other things, lets you see what's nearby and can mark locations on the map.
 +
* The map automatically adapts for display on small-screen devices
 +
* Most views have individual URLs that can be copied and used elsewhere (on web pages, in emails, etc.)
  
 
==API for linking to maps==
 
==API for linking to maps==
  
The front page URL exposes a URL for linking to particular views based on searches - see [[The Map URL API]] for details. For example:
+
The map exposes a URL for linking to particular views based on searches - see [[The Map URL API]] for details. For example:
  
 
* http://map.cam.ac.uk/Computing+Service (location of the UCS)
 
* http://map.cam.ac.uk/Computing+Service (location of the UCS)
Line 12: Line 18:
 
* http://map.cam.ac.uk/saint%20johns%20street ('St John's Street', note lower case, 'saint' vs. 'st', omitted apostrophe, and %20 for space)
 
* http://map.cam.ac.uk/saint%20johns%20street ('St John's Street', note lower case, 'saint' vs. 'st', omitted apostrophe, and %20 for space)
  
There's an extended search syntax, for example
+
There's an extended search syntax, for example:
  
* http://map.cam.ac.uk/?q=dow&partial=partial (everything containing words starting 'do')
+
* http://map.cam.ac.uk/?q=dow&partial=partial (everything containing words starting 'dow')
 
* http://map.cam.ac.uk/?q=saint&filter=college (all colleges with 'saint' in their names, but not roads or anything else)
 
* http://map.cam.ac.uk/?q=saint&filter=college (all colleges with 'saint' in their names, but not roads or anything else)
  
...or based on underlying OSM identifiers, which are Planon IDs for University buildings.
+
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:
  
 
* http://map.cam.ac.uk/?ref=M038 (The Austin Building - note that's a Planon ID)
 
* http://map.cam.ac.uk/?ref=M038 (The Austin Building - note that's a Planon ID)
* http://map.cam.ac.uk/?ref=STEDMUNDS019 (St Endmund's building 019 - extended ID scheme for non-University buildings)
+
* 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)
  
...or on map institution identifiers:
+
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.
 +
 
 +
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]:
  
 
* http://map.cam.ac.uk/?inst=CS (the UCS, by INSTID)
 
* http://map.cam.ac.uk/?inst=CS (the UCS, by INSTID)
  
...or based on physical areas
+
If all else fails you can link to a physical areas:
  
 
* http://map.cam.ac.uk/?bb=52.2043,0.11835,52.2025,0.1216 (New Museums Site)
 
* http://map.cam.ac.uk/?bb=52.2043,0.11835,52.2025,0.1216 (New Museums Site)
 +
 +
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:
 +
 +
* http://map.cam.ac.uk/Hopkinson+Lecture+Theatre#52.199669,0.127349,15
 +
 +
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]].
  
 
==Embedding Maps==
 
==Embedding Maps==
  
All of the URL's above can be used as the source for an iframe to embed the corresponding map in a particular page - see The [[Embedding API]] for details.  
+
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.  
 
 
''These examples use tiles from http://map.cam.ac.uk/ - because it currently requires Raven authentication they won't work properly until you've authenticated (once) to map.cam.ac.uk.''
 
  
 
For example this:
 
For example this:
Line 61: Line 73:
 
  </html>
 
  </html>
  
Produces [http://www-uxsup.csx.cam.ac.uk/~jw35/map-demo/test.html a page like this].
+
Produces [https://demo.map.cam.ac.uk/ucs-iframe.html a page like this].
 +
 
 +
==Annotation==
 +
 
 +
===Manual annotation===
 +
 
 +
The map includes a tool to create and edit map overlays - see [[Map Annotation]] for details.
 +
 
 +
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.:
 +
 
 +
* http://map.cam.ac.uk/#YNKQ-N89P-ZMXP
 +
 
 +
 
 +
Alternatively it can be downloaded and served from any web server and then referenced after the hash part of a map URL, e.g.:
 +
 
 +
* http://map.cam.ac.uk/#https://demo.map.cam.ac.uk/annotation.json
 +
 
 +
===Annotation based on other data===
 +
 
 +
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.
  
Here's a further example: [http://www.ucs.cam.ac.uk/about-us/where the normal UCS 'Where we are' page] reworked to [http://www-uxsup.csx.cam.ac.uk/~jw35/map-demo/where.html use the new map].
+
For example, a static UCamGeoJSON file used to display the locations and identifier of all the Cambridge Colleges:
 +
 
 +
* http://map.cam.ac.uk/#https://demo.map.cam.ac.uk/colleges/colleges.json
 +
 
 +
Or a script that dynamically extracts staircase information direct from the OpenStreetMap database and displays it:
 +
 
 +
* http://map.cam.ac.uk/#/annotate/adapters/staircases.json?ref=PEM
  
 
==Tile API==
 
==Tile API==
Line 69: Line 106:
 
The tiles making up the map are freely available - see [[The Tile API]].  
 
The tiles making up the map are freely available - see [[The Tile API]].  
  
''These examples use tiles from http://map.cam.ac.uk/ - because it currently requires Raven authentication they won't work properly until you've authenticated (once) to map.cam.ac.uk.''
+
Here are [https://demo.map.cam.ac.uk/tiles.html some of the tiles that make up the city centre].
  
Here are [http://www-uxsup.csx.cam.ac.uk/~jw35/map-demo/tiles.html some of the tiles that make up the city centre].
+
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:
  
They follow the conventions of Open Street Map and other similar systems and so can be consumed in various ways.  Here are some examples using third-party map APIs:
+
* [https://demo.map.cam.ac.uk/open-layers.html An example displaying our tiles, OSM's, or Google's] using [http://openlayers.org/ OpenLayers].
 +
* [https://demo.map.cam.ac.uk/leaflet.html An example with marker and shape overlay] using [http://leafletjs.com/ Leaflet]
 +
* [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]
  
* [http://www-uxsup.csx.cam.ac.uk/~jw35/map-demo/open-layers.html An example displaying our tiles, OSM's, or Google's] using [http://openlayers.org/ OpenLayers].
+
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.
* [http://www-uxsup.csx.cam.ac.uk/~jw35/map-demo/leaflet.html An example with marker and shape overlay] using [http://leaflet.cloudmade.com/ Leaflet]
 
* [http://www-uxsup.csx.cam.ac.uk/~jw35/map-demo/google.html A further example combining our tiles and Google's], this time using [https://developers.google.com/maps/ the Google Maps API]
 
  
 
==Index API==
 
==Index API==
Line 83: Line 120:
 
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:
 
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:
  
* http://map.cam.ac.uk/v5.json?q=Computing+Service ([http://map.cam.ac.uk/v5.json?q=Computing+Service&debug=1 debug version])
+
* http://map.cam.ac.uk/v6.json?q=Computing+Service ([http://map.cam.ac.uk/v6.json?q=Computing+Service&debug=1 debug version])
* http://map.cam.ac.uk/v5.json?q=New+Museums+Site ([http://map.cam.ac.uk/v5.json?q=New+Museums+Site&debug=1 debug version])
+
* 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])
* http://map.cam.ac.uk/v5.json?q=saint ([http://map.cam.ac.uk/v5.json?q=saint&debug=1  debug version])
+
* http://map.cam.ac.uk/v6.json?q=saint ([http://map.cam.ac.uk/v6.json?q=saint&debug=1  debug version])
* http://map.cam.ac.uk/v5.json?q=saint%20johns%20street ([http://map.cam.ac.uk/v5.json?q=saint%20johns%20street&debug=1 debug version])
+
* 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])
* http://map.cam.ac.uk/v5.json?q=dow&partial=partial ([http://map.cam.ac.uk/v5.json?q=dow&partial=partial&debug=1 debug version])
+
* 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])
* http://map.cam.ac.uk/v5.json?q=saint&filter=college ([http://map.cam.ac.uk/v5.json?q=saint&filter=college&debug=1 debug version])
+
* 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])
* http://map.cam.ac.uk/v5.json?ref=M038 ([http://map.cam.ac.uk/v5.json?ref=M038&debug=1 debug version])
+
* http://map.cam.ac.uk/v6.json?ref=M038 ([http://map.cam.ac.uk/v6.json?ref=M038&debug=1 debug version])
* http://map.cam.ac.uk/v5.json?ref=STEDMUNDS019 ([http://map.cam.ac.uk/v5.json?ref=STEDMUNDS019&debug=1 debug version])
+
* http://map.cam.ac.uk/v6.json?ref=STEDMUNDS019 ([http://map.cam.ac.uk/v6.json?ref=STEDMUNDS019&debug=1 debug version])
* http://map.cam.ac.uk/v5.json?inst=CS ([http://map.cam.ac.uk/v5.json?inst=CS&debug=1 debug version])
+
* http://map.cam.ac.uk/v6.json?inst=CS ([http://map.cam.ac.uk/v6.json?inst=CS&debug=1 debug version])
* http://map.cam.ac.uk/v5.json?bb=52.2021,0.1184,52.2047,0.1218 ([http://map.cam.ac.uk/v5.json?bb=52.2021,0.1184,52.2047,0.1218&debug=1 debug version])
+
* 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])
 +
* http://map.cam.ac.uk/v6.json?alpha=a ([http://map.cam.ac.uk/v6.json?alpha=a&debug=1 debug version])
 +
 
 +
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.

Latest revision as of 17:50, 20 September 2021

Basic use

See the Map's user help page for further details.

  • The map 'frontpage': http://map.cam.ac.uk/.
  • You can search for most things and once you've found something you'll also get addresses and other contact details.
  • Clicking shows a popup menu that, among other things, lets you see what's nearby and can mark locations on the map.
  • The map automatically adapts for display on small-screen devices
  • Most views have individual URLs that can be copied and used elsewhere (on web pages, in emails, etc.)

API for linking to maps

The map exposes a URL for linking to particular views based on searches - see The Map URL API for details. For example:

There's an extended search syntax, for example:

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:

There's an 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.

It's also possible to construct links based on institution identifiers, which in turn are based on the 'institution Identifiers' used in Lookup:

If all else fails you can link to a physical areas:

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:

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.

Embedding Maps

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.

For example this:

<!DOCTYPE html>
<html>

<head>
<title>Iframe test</title>
<style type="text/css">
#map {
  width: 400px;
  height: 400px;
  border: 1px solid black;
}
</style>
</head>

<body> 

<iframe id="map" src="http://map.cam.ac.uk/Computing+Service">
</iframe>

</body>

</html>

Produces a page like this.

Annotation

Manual annotation

The map includes a tool to create and edit map overlays - see Map Annotation for details.

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.:


Alternatively it can be downloaded and served from any web server and then referenced after the hash part of a map URL, e.g.:

Annotation based on other data

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.

For example, a static UCamGeoJSON file used to display the locations and identifier of all the Cambridge Colleges:

Or a script that dynamically extracts staircase information direct from the OpenStreetMap database and displays it:

Tile API

The tiles making up the map are freely available - see The Tile API.

Here are some of the tiles that make up the city centre.

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:

In addition, these tiles can be used with stand-alone programs that expect the OpenStreetMap conventions - for example they have been used with both OpenMaps and GlobalScout under iOS.

Index API

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:

The interactive browser (also linked from the 'More...' menu) can be useful for identifying the various codes in use.