The Map URL API: Difference between revisions

From University Map Wiki
Jump to navigationJump to search
(Oops - www.cam --> map.cam)
(Replace webtools links with links to demo.map, new home of those files)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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>http://map.cam.ac.uk/x/?q=s</strong> is exactly the same as <strong>http://map.cam.ac.uk/x?q=s</strong>).
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>).


<table class="wikitable">
<table class="wikitable">
Line 12: Line 12:
<tr>
<tr>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
http://map.cam.ac.uk/</td>
<nowiki>https://map.cam.ac.uk/</nowiki></td>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
displays the home page of the University map</td>
displays the home page of the University map</td>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
http://map.cam.ac.uk/</td>
https://map.cam.ac.uk/</td>
</tr>
</tr>
<tr>
<tr>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
http://map.cam.ac.uk/<em>name</em></td>
<nowiki>https://map.cam.ac.uk/</nowiki><em>name</em></td>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
<p>
<p>
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;http://map.cam.ac.uk/q=<em>name</em>&#39; (see below).</p>
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>
<p>
<p>
<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>
<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>
Line 31: Line 31:
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
<p>
<p>
http://map.cam.ac.uk/Lucy+Cavendish+College</p>
https://map.cam.ac.uk/Lucy+Cavendish+College</p>
<p>
<p>
http://map.cam.ac.uk/austin%20building</p>
https://map.cam.ac.uk/austin%20building</p>
<p>
<p>
http://map.cam.ac.uk/Fenner%27s</p>
https://map.cam.ac.uk/Fenner%27s</p>
<p>
<p>
http://map.cam.ac.uk/Tennis+Court+Road</p>
https://map.cam.ac.uk/Tennis+Court+Road</p>
<p>
<p>
M:/fitzwilliam+st</p>
https://map.cam.ac.uk/fitzwilliam+st</p>
<p>
<p>
http://map.cam.ac.uk/queens+college<br />
https://map.cam.ac.uk/queens+college<br />
(note the absence of apostrophe).</p>
(note the absence of apostrophe).</p>
</td>
</td>
Line 47: Line 47:
<tr>
<tr>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
http://map.cam.ac.uk/?ref=<em>ref</em></td>
<nowiki>https://map.cam.ac.uk/?</nowiki>ref=<em>ref</em></td>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
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;. Where buildings or sites are selected the corresponding main entrances are also displayed.</td>
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>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
<p>
<p>
http://map.cam.ac.uk/?ref=STEDMUNDS019<br />
https://map.cam.ac.uk/?ref=STEDMUNDS019<br />
(which is the Library building in St Edmund&#39;s College)</p>
(which is the Library building in St Edmund&#39;s College)</p>
<p>
<p>
http://map.cam.ac.uk/?ref=WOLFSON--W<br />
https://map.cam.ac.uk/?ref=WOLFSON--W<br />
(Wolfson College W staircase)<br />
(Wolfson College W staircase)<br />
&nbsp;</p>
&nbsp;</p>
Line 62: Line 62:
<tr>
<tr>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
http://map.cam.ac.uk/?inst=<em>inst</em></td>
<nowiki>https://map.cam.ac.uk/?</nowiki>inst=<em>inst</em></td>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
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;.</td>
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>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
<p>
<p>
http://map.cam.ac.uk/?inst=CS<br />
https://map.cam.ac.uk/?inst=CS<br />
(computing service)</p>
(computing service)</p>
<p>
<p>
http://map.cam.ac.uk/?inst=ucs<br />
https://map.cam.ac.uk/?inst=cs<br />
(ditto)</p>
(ditto)</p>
<p>
<p>
http://map.cam.ac.uk/?inst=lcc<br />
https://map.cam.ac.uk/?inst=lcc<br />
(Lucy Cavendish College)</p>
(Lucy Cavendish College)</p>
<p>
<p>
http://map.cam.ac.uk/?inst=lucy-cav|joh<br />
https://map.cam.ac.uk/?inst=lucy-cav|joh<br />
(lucy Cavendish and St John&#39;s Colleges)</p>
(lucy Cavendish and St John&#39;s Colleges)</p>
</td>
</td>
Line 82: Line 82:
<tr>
<tr>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
http://map.cam.ac.uk/?q=<em>search</em><br />
<nowiki>https://map.cam.ac.uk/?</nowiki>q=<em>search</em><br />
[&amp;one=list]<br />
[&amp;one=list]<br />
[&amp;partial<em>=</em>partial]<br />
[&amp;partial<em>=</em>yes]<br />
[&amp;filter=<em>filter</em>]</td>
[&amp;filter=<em>filter</em>]</td>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
Line 92: Line 92:
&#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>
&#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>
<p>
<p>
If &#39;partial=partial&#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>
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>
 
<p>
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>
 
<p>
<p>
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>
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>
<p>
<p>
Note that if the search yields only one result and the optional parameters are omitted, then the result is identical to the URL M:/<em>name </em>as above.</p>
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>
</td>
</td>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
<p>
<p>
http://map.cam.ac.uk/?q=Lucy+Cavendish+College</p>
https://map.cam.ac.uk/?q=Lucy+Cavendish+College</p>
<p>
<p>
http://map.cam.ac.uk/?q=lucy|queens</p>
https://map.cam.ac.uk/?q=lucy|queens</p>
<p>
<p>
http://map.cam.ac.uk/?q=Wolfson+College&amp;one=list</p>
https://map.cam.ac.uk/?q=Wolfson+College&amp;one=list</p>
<p>
<p>
M?q=Do&amp;partial=yes<br />
https://map.cam.ac.uk/?q=Do&amp;partial=yes<br />
(which might yield results for Downing College, Downing Street, Downing Place, Downing Site and Doubletree by Hilton).</p>
(which might yield results for Downing College, Downing Street, Downing Place, Downing Site and Doubletree by Hilton).</p>
<p>
<p>
http://map.cam.ac.uk/?q=Do<br />
https://map.cam.ac.uk/?q=Do<br />
(produces no results)</p>
(produces no results)</p>
<p>
<p>
http://map.cam.ac.uk/?q=sussex&amp;filter=college</p>
https://map.cam.ac.uk/?q=sussex&amp;filter=college</p>
</td>
</td>
</tr>
</tr>
Line 118: Line 122:
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
<p>
<p>
http://map.cam.ac.uk/?bb=<em>lat0,lon0,lat1,lon1</em><br />
<nowiki>https://map.cam.ac.uk/?</nowiki>bb=<em>lat0,lon0,lat1,lon1</em><br />
[&amp;z=<em>zoom</em>]<br />
[&amp;one=list]<br />
[&amp;one=list]<br />
[&amp;filter=<em>filter</em>]</p>
[&amp;filter=<em>filter</em>]</p>
Line 125: Line 128:
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
<p>
<p>
the equivalent of searching, except by bounding box rather than text string. Typically this is the URL derived by zooming in or out from an existing map. Content is filtered according to the zoom level, when provided, so that an overwhelming amount of information is not produced for low zoom. Note: no spaces after commas.</p>
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>
<p>
<p>
filter as above</p>
filter as above</p>
</td>
</td>
<td style="vertical-align: top; ">
<td style="vertical-align: top; ">
http://map.cam.ac.uk/?bb=52.2021,0.1184,52.2047,0.1218&amp;z=19</td>
https://map.cam.ac.uk/?bb=52.2021,0.1184,52.2047,0.1218</td>
</tr>
</tr>
</table>
</table>
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:
  <nowiki>
https://map.cam.ac.uk/#52.206397,0.114015,16
https://map.cam.ac.uk/#https://demo.map.cam.ac.uk/annotation.json
https://map.cam.ac.uk/#52.206397,0.114015,16,https://demo.map.cam.ac.uk/annotation.json
  </nowiki>
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.
  <nowiki>
https://map.cam.ac.uk/#z
https://map.cam.ac.uk/#lat,lon
https://map.cam.ac.uk/#lat,lon,z
https://map.cam.ac.uk/#lat,lon,mlat,mlon
https://map.cam.ac.uk/#lat,lon,z,mlat,mlon
https://map.cam.ac.uk/#lat,lon,z,mlat0,mlon0,mlat1,mlon1,...</nowiki>
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.
'''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.

Latest revision as of 17:49, 20 September 2021

URLs have the following structure. Note that in all cases where a query string follows a directory the separating '/' is optional (i.e. https://map.cam.ac.uk/x/?q=s is exactly the same as https://map.cam.ac.uk/x?q=s).

URL Description Examples
https://map.cam.ac.uk/ displays the home page of the University map https://map.cam.ac.uk/
https://map.cam.ac.uk/name

displays the map homed in on the item called name. name 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 'http://map.cam.ac.uk/?q=name' (see below).

If you want to link to a map on the centrally hosted site, this is the best kind of URL to use. But consider embedding a map: see below.

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 'AKA' field.

https://map.cam.ac.uk/Lucy+Cavendish+College

https://map.cam.ac.uk/austin%20building

https://map.cam.ac.uk/Fenner%27s

https://map.cam.ac.uk/Tennis+Court+Road

https://map.cam.ac.uk/fitzwilliam+st

https://map.cam.ac.uk/queens+college
(note the absence of apostrophe).

https://map.cam.ac.uk/?ref=ref displays the map homed in on the item(s) referenced ref. References are geographical information and refer to entrances, buildings and sites/colleges as indicated by the ref=... tag on the corresponding OpenStreetMap data. ref can also be a list of references separated by '|' (up to 25 can be requested at once). Where buildings or sites are selected the corresponding main entrances are also displayed.

https://map.cam.ac.uk/?ref=STEDMUNDS019
(which is the Library building in St Edmund's College)

https://map.cam.ac.uk/?ref=WOLFSON--W
(Wolfson College W staircase)
 

https://map.cam.ac.uk/?inst=inst displays the map homed in on institution(s) identified by inst, the institution code, which is case insensitive, or a list of these separated by '|' (up to 25 can be requested at once).

https://map.cam.ac.uk/?inst=CS
(computing service)

https://map.cam.ac.uk/?inst=cs
(ditto)

https://map.cam.ac.uk/?inst=lcc
(Lucy Cavendish College)

https://map.cam.ac.uk/?inst=lucy-cav%7Cjoh
(lucy Cavendish and St John's Colleges)

https://map.cam.ac.uk/?q=search
[&one=list]
[&partial=yes]

[&filter=filter]

displays the map page with results of the search for the URL encoded string search. Multiple search strings may be given separated by '|'

'one=list' 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.

If 'partial=yes' (or in fact, 'partial=anything else') 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).

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

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 "filter=college|academic": college, academic, site, nonacademic, lecture, techno, street, nonuniversity.

Note that if the search yields only one result and the optional parameters are omitted, then the result is identical to the URL https://map.cam.ac.uk/name as above.

https://map.cam.ac.uk/?q=Lucy+Cavendish+College

https://map.cam.ac.uk/?q=lucy%7Cqueens

https://map.cam.ac.uk/?q=Wolfson+College&one=list

https://map.cam.ac.uk/?q=Do&partial=yes
(which might yield results for Downing College, Downing Street, Downing Place, Downing Site and Doubletree by Hilton).

https://map.cam.ac.uk/?q=Do
(produces no results)

https://map.cam.ac.uk/?q=sussex&filter=college

https://map.cam.ac.uk/?bb=lat0,lon0,lat1,lon1
[&one=list]
[&filter=filter]

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

filter as above

https://map.cam.ac.uk/?bb=52.2021,0.1184,52.2047,0.1218

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 manually, using UCamGeoJSON or 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:

 
 https://map.cam.ac.uk/#52.206397,0.114015,16
 https://map.cam.ac.uk/#https://demo.map.cam.ac.uk/annotation.json
 https://map.cam.ac.uk/#52.206397,0.114015,16,https://demo.map.cam.ac.uk/annotation.json
  

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.

 
 https://map.cam.ac.uk/#z
 https://map.cam.ac.uk/#lat,lon
 https://map.cam.ac.uk/#lat,lon,z
 https://map.cam.ac.uk/#lat,lon,mlat,mlon
 https://map.cam.ac.uk/#lat,lon,z,mlat,mlon
 https://map.cam.ac.uk/#lat,lon,z,mlat0,mlon0,mlat1,mlon1,...

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.

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.