Difference between revisions of "The Database API reference discovery"

From University Map Wiki
Jump to navigationJump to search
 
(20 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
This page describes how the (version 6) University Map Database API can be used to navigate among geographical objects and thereby determine relevant ref codes.
 
This page describes how the (version 6) University Map Database API can be used to navigate among geographical objects and thereby determine relevant ref codes.
 +
 +
==Quick start==
 +
 +
Use the API to get a list of geographic items using a wildcard, as in
 +
 +
  [http://map.cam.ac.uk/v6.json?ref=M*&debug=1 http://map.cam.ac.uk/v6.json?ref=M*]
 +
 +
Substitute the wildcard for just one of the elements that make up a reference, as listed in [[The_Database_API_reference_discovery#In_summary|the table below]].
  
 
==Introduction==
 
==Introduction==
Line 11: Line 19:
 
However, this assumes you know what the refs are.
 
However, this assumes you know what the refs are.
  
For those buildings etc which have names, searching for them by name either with the API or the interactive map will provide the record from which its ref can be determined. But (a) colleges yield the institution not the geographical college site when looked up by name, and (b) many entities, especially entrances, do not have names at all.
+
For those buildings etc which have names, searching for them by name either with the API or the interactive map will provide the record from which its ref can be determined. But
 +
* colleges yield the institution, not the geographical college site when looked up by name, and
 +
* many entities, especially entrances, do not have names at all.
  
 
Therefore, both the API and the interactive also provide the ability to look up all the subordinate geographical entities for some entity (the geographical entities are arranged in a hierarchy) using a '''wildcard''' and thereby determine related (and ultimately, if necessary, all) references. For example, using the API:
 
Therefore, both the API and the interactive also provide the ability to look up all the subordinate geographical entities for some entity (the geographical entities are arranged in a hierarchy) using a '''wildcard''' and thereby determine related (and ultimately, if necessary, all) references. For example, using the API:
  
   http://map.cam.ac.uk/v6.json?ref=M*
+
   [http://map.cam.ac.uk/v6.json?ref=M*&debug=1 http://map.cam.ac.uk/v6.json?ref=M*]
  
 
and for the interactive map
 
and for the interactive map
  
   http://map.cam.ac.uk/?ref=M*
+
   [http://map.cam.ac.uk/?ref=M*&debug=1 http://map.cam.ac.uk/?ref=M*]
  
 
==Geographical entity hierarchy==
 
==Geographical entity hierarchy==
Line 26: Line 36:
  
 
* site (comprising university properties grouped in one physical location)
 
* site (comprising university properties grouped in one physical location)
* college (which is like a site, but refers to college properties)
+
* college (which is like a site, but refers to college properties; many Colleges have multiple college sites)
 
* building
 
* building
* entrance (to a building or to a site)
+
* entrance (to a building or to a site or college)
 
* nonuniversity (selected buildings/sites useful to display and reference)
 
* nonuniversity (selected buildings/sites useful to display and reference)
  
Line 39: Line 49:
 
     |        |----- building/sub-building
 
     |        |----- building/sub-building
 
     |        |        |
 
     |        |        |
     |        |        |----- (building) entrance
+
     |        |        |----- entrance (to building)  
 
     |        |
 
     |        |
     |        |----- (site) entrance
+
     |        |----- entrance (to subsite)  
 
     |        |
 
     |        |
     |        |----- (staircase) entrance
+
     |        |----- entrance (staircase)
 
     |
 
     |
 
     |----- building/sub-building
 
     |----- building/sub-building
 
     |        |
 
     |        |
     |        |----- (building) entrance
+
     |        |----- entrance (to building)
 
     |
 
     |
     |----- (site) entrance
+
     |----- entrance (to site)
 
     |
 
     |
     |----- (staircase) entrance
+
     |----- entrance (staircase)
  
 
A subsite looks just like a site, but represents a lesser group of buildings. It is not geographically contained within a site, but is linked to a parent site because of the way in which University Property Codes have historically been organised, and in the case of colleges because many colleges have separate outlying subsites.
 
A subsite looks just like a site, but represents a lesser group of buildings. It is not geographically contained within a site, but is linked to a parent site because of the way in which University Property Codes have historically been organised, and in the case of colleges because many colleges have separate outlying subsites.
Line 59: Line 69:
 
==References explained==
 
==References explained==
  
The hierarchy is reflected in the syntax of references, the codes which uniquely identify these entities. These reference codes are store along with their outlines in OpenStreetMap from which the data is obtained, using the property ("tag") '''ref'''.
+
The hierarchy is reflected in the syntax of references, the codes which uniquely identify these entities. These reference codes are stored along with their outlines in OpenStreetMap from which the data is obtained, using the property ("tag") '''ref'''.
  
References derive originally from University Estates Department property codes. These do not include college properties, so the numbering scheme has been extended to include these, and do not originally have any concept of subsites.  
+
References derive originally from University Estates Department property codes. These do not include college properties, so the numbering scheme has been extended to include these, and did not originally have any concept of subsites.  
  
These property codes comprise an upper case letter which identifies a site followed by three digits identifying the building. For example M039 is the [http://map.cam.ac.uk/?ref=M039 Cockcroft Building] on the [http://map.cam.ac.uk/?ref=M New Museums Site ("M")]. (Estates did use an earlier numbering scheme which can be seen on the white sign boards at many entrances to the central sites. However these were abandoned in favour of this more regular scheme, and the sign boards have just not been updated).
+
These property codes comprise an upper case letter which identifies a site followed by three digits identifying the building. For example '''M039''' is the [http://map.cam.ac.uk/?ref=M039 Cockcroft Building] on the [http://map.cam.ac.uk/?ref=M New Museums Site ('''M''')]. (Estates did use an earlier numbering scheme which can be seen on the white sign boards at many entrances to the central sites. However these were abandoned in favour of this more regular scheme, and the sign boards have just not been updated).
  
Sometimes it is useful to represent an "Estates" building as more than one building, either because it actually is more than one (usually abutting) physical structure, or a code has been used to cover a group of not-very-distinct buildings, as in some of the farms, or it is useful to break up a large building into pieces where it is occupied in distinct parts (the Austin Robinson Building on the Sidgwick Site for example). These are represented by adding a period and another number to the reference (a decimal part, if you like). For example, the southern part of the Austin Robinson Building (the bit with the [http://map.cam.ac.uk/Sidgwick+Buttery Sidgwick Buttery]) is S012.3
+
Sometimes it is useful to represent an "Estates" building as more than one building, either because it actually is more than one (usually abutting) physical structure, or a code has been used to cover a group of not-very-distinct buildings, as in some of the farms, or it is useful to break up a large building into pieces where it is occupied in distinct parts (the Austin Robinson Building on the Sidgwick Site for example). These are represented by adding a period and another number to the reference (a decimal part, if you like). For example, the southern part of the Austin Robinson Building (the bit with the [http://map.cam.ac.uk/Sidgwick+Buttery Sidgwick Buttery]) is '''S012.3'''
  
Entrances are then represented by the building (for doors) or site (for gates etc) by the  building or site code followed by a dash and one or more upper case letters. For example S012.3-A
+
Entrances are then represented by the building (for doors) or site (for gates etc) by the  building or site code followed by a dash and one or more upper case letters. For example '''S012.3-A'''
  
 
Subsites are formed by following the site code with a slash and some more upper case letters. For example L/MATHS is the group of buildings and grounds of the [http://map.cam.ac.uk?ref=S/MATHS Centre for Mathematical Studies].
 
Subsites are formed by following the site code with a slash and some more upper case letters. For example L/MATHS is the group of buildings and grounds of the [http://map.cam.ac.uk?ref=S/MATHS Centre for Mathematical Studies].
  
Colleges follow the same pattern. Their codes for their main sites are their sub-domain names in upper case. For example CLARE for [http://map.cam.ac.uk?ref=CLARE Clare College]. Outliers are just like subsites, hence CLARE/MEM is Clare's [http://map.cam.ac.uk?ref=CLARE/MEM Memorial Court] property. Note that LUCY-CAV is unusual, being the only one with a dash in the code, so if you are parsing references using regular expressions, you need to allow for this.
+
Colleges follow the same pattern. Their codes for their main sites are their sub-domain names in upper case. For example '''CLARE''' for [http://map.cam.ac.uk?ref=CLARE Clare College]. Outliers are just like subsites, hence '''CLARE/MEM''' is Clare's [http://map.cam.ac.uk?ref=CLARE/MEM Memorial Court] property. Note that '''LUCY-CAV''' is unusual, being the only one with a dash in the code, so if you are parsing references using regular expressions, you need to allow for this.
  
Finally, college staircases, though individually part of particular buildings, are actually represented college-wide. Hence they are subiordinate to college sites and subsites, and their letter is separated from the site code by two dashes. Thus DOW--P is [http://map.cam.ac.uk/?ref=DOW--P Downing's P staircase], which happens to be in the [http://map.cam.ac.uk/?ref=DOW029 East Range] though there is nothing to tell you that.
+
Finally, college staircases, though individually part of particular buildings, are actually represented college-wide. Hence they are subiordinate to college sites and subsites, and their letter is separated from the site code by two dashes. Thus '''DOW--P''' is [http://map.cam.ac.uk/?ref=DOW--P Downing's P staircase], which happens to be in the [http://map.cam.ac.uk/?ref=DOW029 East Range] though there is nothing to tell you that.
  
===In detail===
+
===In summary===
  
 
If X stands for one or more upper case letters, nnn for three digits and n for digits in general,
 
If X stands for one or more upper case letters, nnn for three digits and n for digits in general,
Line 91: Line 101:
 
==Reference browser==
 
==Reference browser==
  
For casual use to determine a reference, and for illustration of the API, a live reference hierarchy browser is under construction. This will be at  
+
For casual use to determine a reference, and for illustration of the API, there is a live reference hierarchy browser at  
  
   http://map.cam.ac.uk/help/refbrowser/
+
   http://map.cam.ac.uk/refbrowser/
  
 
This uses exactly the API wildcard requests as shown below.
 
This uses exactly the API wildcard requests as shown below.
Line 105: Line 115:
 
A single asterisk provides a starting point in the absence of any other, providing all the top-level sites and colleges, thus (using the API):
 
A single asterisk provides a starting point in the absence of any other, providing all the top-level sites and colleges, thus (using the API):
  
   http://map.cam.ac.uk/v6.json?ref=*
+
   [http://map.cam.ac.uk/v6.json?ref=*&debug=1 http://map.cam.ac.uk/v6.json?ref=*]
  
This pattern uniquely also yields a few objects of type pseudo-site, which are just like site except that they have no location information associated with them. Looking up their ref verbatim will yield no results. They are provided so that the complete set of prefix letters is available as a starting point. Furthermore, a Cambridge Biomedical Campus nonuniversity object is included, for which buildings, entrances and subsites require the operator part of the reference (before a colon: see below) to be removed (which in practice will leave just site code 'H'); should any other nonuniversity sites arise in future with university property codes within, they will be managed in the same way, so it is preferable not to assume 'H' but to strip off everything up to and including the colon in the ref for such sites. See the reference table for more information about the psuedo-sites.
+
This pattern, like that for subsites below, also yields a few objects of type '''virtualsite''', which are just like '''site''' except that they have no location information associated with them. Looking up their ref verbatim will yield no results. They are provided so that the complete set of prefix letters is available as a starting point. One of these is a grouping for non-university premises, with ref 'EXT'.
  
Given a particular site, CLARE say (obtained from the result of the above) one can then obtain all its subsites (if any), thus:
+
Furthermore, a Cambridge Biomedical Campus '''site''' object is included with site code 'H', which is a non-university site. Both 'H' and 'EXT' include a nonuniversity boolean member to distinguish them (use to colour them differently in the University map).
  
   http://map.cam.ac.uk/v6.json?ref=CLARE/*
+
Given a particular site, '''CLARE''' say (obtained from the result of the above) one can then obtain all its subsites (if any), thus:
 +
 
 +
   [http://map.cam.ac.uk/v6.json?ref=CLARE/*&debug=1 http://map.cam.ac.uk/v6.json?ref=CLARE/*]
  
 
Note that buildings of a site or subsite yields sub-buildings as well, because they aren't actually subdivisions, thus:
 
Note that buildings of a site or subsite yields sub-buildings as well, because they aren't actually subdivisions, thus:
  
   http://map.cam.ac.uk/v6.json?ref=S*
+
   [http://map.cam.ac.uk/v6.json?ref=S*&debug=1 http://map.cam.ac.uk/v6.json?ref=S*]
  
includes S031.3 (as in the example above). However, one can also obtain the sub-buildings of a building code even if the building that would be represented with that code does not actually exist. Hence:
+
includes '''S013.3''' (as in the example above). However, one can also obtain the sub-buildings of a building code even if the building that would be represented with that code does not actually exist. Hence:
  
   http://map.cam.ac.uk/v6.json?ref=S031.*
+
   [http://map.cam.ac.uk/v6.json?ref=S013.*&debug=1 http://map.cam.ac.uk/v6.json?ref=S013.*]
  
 
This is useful in circumstances where you have the original property code but don't know whether it is divided up or not in the map. This will be useful in those circumstances.
 
This is useful in circumstances where you have the original property code but don't know whether it is divided up or not in the map. This will be useful in those circumstances.
  
   http://map.cam.ac.uk/v6.json?ref=SO31|S031.*
+
   [http://map.cam.ac.uk/v6.json?ref=SO13|S013.*&debug=1 http://map.cam.ac.uk/v6.json?ref=SO13|S013.*]
  
 
All the staircases at Clare College (main site only):
 
All the staircases at Clare College (main site only):
  
   http://map.cam.ac.uk/v6.json?ref=CLARE--*
+
   [http://map.cam.ac.uk/v6.json?ref=CLARE--*&debug=1 http://map.cam.ac.uk/v6.json?ref=CLARE--*]
  
 
and at Memorial Court:
 
and at Memorial Court:
  
   http://map.cam.ac.uk/v6.json?ref=CLARE/MEM--*
+
   [http://map.cam.ac.uk/v6.json?ref=CLARE/MEM--*&debug=1 http://map.cam.ac.uk/v6.json?ref=CLARE/MEM--*]
  
 
===Results===
 
===Results===
Line 141: Line 153:
 
===Combining patterns===
 
===Combining patterns===
  
As with non-wildcard references, several can be requested at once, separating them with a vertical bar. Therefore, all entrances of both M031.1, M031.2 and M031.3 can be obtained thus:
+
As with non-wildcard references, several can be requested at once, separating them with a vertical bar. Therefore, all entrances of '''M031.1''', '''M031.2''' and '''M031.3''' can be obtained thus:
  
   http://map.cam.ac.uk/v6.json?ref=M031.1-*|M031.2-*|M031.3-*
+
   [http://map.cam.ac.uk/v6.json?ref=M031.1-*|M031.2-*|M031.3-*&debug=1 http://map.cam.ac.uk/v6.json?ref=M031.1-*|M031.2-*|M031.3-*]
  
 
Note that you ''can't'' use ref=M031.*-* as you can only have one wildcard per reference.
 
Note that you ''can't'' use ref=M031.*-* as you can only have one wildcard per reference.
Line 149: Line 161:
 
===Non university premises===
 
===Non university premises===
  
In general, non-university premises do not have standard University property codes, for obvious reasons. They may not even have ref tags in OpenStreetMap. Therefore their "reference" is more general, comprising the name of the operator of the premises, followed by a colon, followed the the 'ref' if there is one or the building or site name (which may be the same as the operator name) if not. For example:
+
Non-university premises often do not have standard University property codes, for obvious reasons. When they do, however, it is provided in OpenStreetMap by the ref:university_of_cambridge tag rather than just ref. These may be common university estate references where a building is owned by the University but let to or used by a third party; others are grouped into the virtual site with reference '''EXT''' (or for Addenbrooke's/Cambridge Biomedical Campus buildings etc, '''H''').
 
 
  Arbury Road Baptist Church:Arbury Road Baptist Church
 
  Anglia Ruskin University:Anglia Ruskin University (Cambridge Campus)
 
 
 
No particular distinction is made between sites and buildings for non-university properties in the record returned (though they are drawn differently on the map).
 
 
 
There are a few buildings and sites operated by non-university organisations which ''do'' actually have University property codes (usually because they are leased from the University). Hence MRC-CBU occupies:
 
 
 
  Medical Research Council:L050
 
 
 
In this case, note that all its entrances can be obtained with
 
 
 
  http://map.cam.ac.uk/v6.json?ref=L050-*
 
 
 
not including the "Medical Research Council:" part. Similarly the Cambridge Biomedical Campus site is referenced
 
  
  Cambridge University Hospitals NHS Foundation Trust:H
+
Those that do have a reference are included in the general site/sub-site/building scheme and distinguished by a '''nonuniversity''' boolean member. Those that don't are objects of their own nonuniversity type.
  
In this case drop both the part before the colon for subordinate University buildings and subsites related to this non-University site.
+
(Note: the previous clumsy scheme using operators, colons and names has been removed).
  
 
==Other starting points==
 
==Other starting points==
Line 178: Line 175:
 
* By bounding box. Using a 'bb' query, one can obtain all institutions within an area, and these can be filtered by institution class as in filter=academic|nonacademic. However, it is also possible to use filters for '''site''' (which includes college sites, as opposed to college institutions, and includes subsites), '''building''' and '''entrance''' within an area. When qualify with any of these, institutions are ''not'' also returned unless you also explicitly filter for them. Thus filter=building only yields buildings. The centroid of buildings and sites must lie within the bounding box for them to be located, except that when requesting sites, if any main entrance of the site (not its buildings) falls within the box, the site ''is'' found.<br/><br/>For example, this provides all of the buildings in and around the New Museums Site:
 
* By bounding box. Using a 'bb' query, one can obtain all institutions within an area, and these can be filtered by institution class as in filter=academic|nonacademic. However, it is also possible to use filters for '''site''' (which includes college sites, as opposed to college institutions, and includes subsites), '''building''' and '''entrance''' within an area. When qualify with any of these, institutions are ''not'' also returned unless you also explicitly filter for them. Thus filter=building only yields buildings. The centroid of buildings and sites must lie within the bounding box for them to be located, except that when requesting sites, if any main entrance of the site (not its buildings) falls within the box, the site ''is'' found.<br/><br/>For example, this provides all of the buildings in and around the New Museums Site:
  
   http://map.cam.ac.uk/v6.json?bb=52.2021,0.1184,52.2047,0.1218&filter=building
+
   [http://map.cam.ac.uk/v6.json?bb=52.2021,0.1184,52.2047,0.1218&filter=building&debug=1 http://map.cam.ac.uk/v6.json?bb=52.2021,0.1184,52.2047,0.1218&filter=building]
  
 
* For college staircases, you can guess! The college code is its upper case sub domain and the staircase letter is used in the reference code. So if you want staircase P in Downing, it is easy to ask for ref=DOW--P
 
* For college staircases, you can guess! The college code is its upper case sub domain and the staircase letter is used in the reference code. So if you want staircase P in Downing, it is easy to ask for ref=DOW--P
Line 189: Line 186:
  
 
<tr><td><strong>code</strong></td> <td><strong>description</strong></td> <td><strong>notes</strong></td></tr>
 
<tr><td><strong>code</strong></td> <td><strong>description</strong></td> <td><strong>notes</strong></td></tr>
<tr><td>A</td> <td>Old Schools area</td> <td>there is no site 'A' but the buildings in this area are coded ''Annn''</td></tr>
+
<tr><td>A</td> <td>Old Schools area</td> <td>virtual site: there is no site called 'A' but the buildings in this area are coded ''Annn''</td></tr>
 
<tr><td>B</td> <td>Silver Street/Mill Lane Site</td> <td></td> </tr>
 
<tr><td>B</td> <td>Silver Street/Mill Lane Site</td> <td></td> </tr>
<tr><td>C</td> <td>Scroope Terrace area</td> <td>there is no site 'C' but the buildings in this area are coded ''Cnnn'' and there are several subsites C/''X''</td></tr>
+
<tr><td>C</td> <td>Scroope Terrace area</td> <td>virtual site: buildings in this area are coded ''Cnnn'' and there are several subsites C/''X''</td></tr>
 
<tr><td>CUP</td> <td>Cambridge University Press</td> <td>CUP is treated as part of the University for the purposes of the map</td> </tr>
 
<tr><td>CUP</td> <td>Cambridge University Press</td> <td>CUP is treated as part of the University for the purposes of the map</td> </tr>
 
<tr><td>D</td> <td>Downing Site</td> <td></td> </tr>
 
<tr><td>D</td> <td>Downing Site</td> <td></td> </tr>
 
<tr><td>E</td> <td>Old Addenbrooke's Site</td> <td></td> </tr>
 
<tr><td>E</td> <td>Old Addenbrooke's Site</td> <td></td> </tr>
 +
<tr><td>EXT</td> <td>"external"</td> <td>virtual, nonuniversity site to group non-university (and non-hospital) buildings conveniently</td> </tr>
 
<tr><td>F</td> <td>"farms"</td> <td>includes buildings like the Agronomy Unit</td> </tr>
 
<tr><td>F</td> <td>"farms"</td> <td>includes buildings like the Agronomy Unit</td> </tr>
 
<tr><td>H</td> <td>"hospital", the Cambridge Biomedical Campus</td> <td>the site is nonuniversity, but University premises within it are prefixed H in the usual way</td> </tr>
 
<tr><td>H</td> <td>"hospital", the Cambridge Biomedical Campus</td> <td>the site is nonuniversity, but University premises within it are prefixed H in the usual way</td> </tr>
<tr><td>K</td> <td>north city</td> <td>no site, but several subsites and individual buildings in the north part of Cambridge</td> </tr>
+
<tr><td>K</td> <td>north city</td> <td>virtual site</td> </tr>
<tr><td>L</td> <td>south city</td> <td>no site, but several subsites and individual buildings in the south part of Cambridge</td> </tr>
+
<tr><td>L</td> <td>south city</td> <td>virtual site</td> </tr>
 
<tr><td>M</td> <td>New Museums Site</td> <td></td> </tr>
 
<tr><td>M</td> <td>New Museums Site</td> <td></td> </tr>
 
<tr><td>R</td> <td>Mullard Radio Astronomy Observatory (MRAO)</td> <td></td> </tr>
 
<tr><td>R</td> <td>Mullard Radio Astronomy Observatory (MRAO)</td> <td></td> </tr>
<tr><td>S</td> <td>Sidgwick Site</td> <td>as well as the site, there are numerous outlying buildings to the west of Cambridge prefixed with S and a number of subsites</td> </tr>
+
<tr><td>S</td> <td>Sidgwick Site</td> <td>as well as the site, there are numerous outlying buildings to the west of Cambridge prefixed with S and a number of subsites (e.g. S/MATHS)</td> </tr>
 
<tr><td>T</td> <td>Madingley Rise Site</td> <td></td> </tr>
 
<tr><td>T</td> <td>Madingley Rise Site</td> <td></td> </tr>
 
<tr><td>W</td> <td>West Cambridge Site</td> <td></td> </tr>
 
<tr><td>W</td> <td>West Cambridge Site</td> <td></td> </tr>

Latest revision as of 20:13, 23 February 2015

This page describes how the (version 6) University Map Database API can be used to navigate among geographical objects and thereby determine relevant ref codes.

Quick start

Use the API to get a list of geographic items using a wildcard, as in

 http://map.cam.ac.uk/v6.json?ref=M*

Substitute the wildcard for just one of the elements that make up a reference, as listed in the table below.

Introduction

API calls of the form

 http://map.cam.ac.uk/v6.json?ref=ref|ref|...

yield the geographical entities (buildings, sites, colleges, entrances and nonuniversity premises known to the map) with the given refs.

However, this assumes you know what the refs are.

For those buildings etc which have names, searching for them by name either with the API or the interactive map will provide the record from which its ref can be determined. But

  • colleges yield the institution, not the geographical college site when looked up by name, and
  • many entities, especially entrances, do not have names at all.

Therefore, both the API and the interactive also provide the ability to look up all the subordinate geographical entities for some entity (the geographical entities are arranged in a hierarchy) using a wildcard and thereby determine related (and ultimately, if necessary, all) references. For example, using the API:

 http://map.cam.ac.uk/v6.json?ref=M*

and for the interactive map

 http://map.cam.ac.uk/?ref=M*

Geographical entity hierarchy

There are five kinds of geographical entity stored in the University Map database:

  • site (comprising university properties grouped in one physical location)
  • college (which is like a site, but refers to college properties; many Colleges have multiple college sites)
  • building
  • entrance (to a building or to a site or college)
  • nonuniversity (selected buildings/sites useful to display and reference)

Except for nonuniversity, which stands alone, these are organised into a hierarchy.

 site/college
    |
    |----- subsite
    |        |
    |        |----- building/sub-building
    |        |        |
    |        |        |----- entrance (to building) 
    |        |
    |        |----- entrance (to subsite) 
    |        |
    |        |----- entrance (staircase)
    |
    |----- building/sub-building
    |        |
    |        |----- entrance (to building)
    |
    |----- entrance (to site)
    |
    |----- entrance (staircase)

A subsite looks just like a site, but represents a lesser group of buildings. It is not geographically contained within a site, but is linked to a parent site because of the way in which University Property Codes have historically been organised, and in the case of colleges because many colleges have separate outlying subsites.

A sub-building is just a convenient mechanism for broadening the property codes while keeping the underlying numbering scheme.

References explained

The hierarchy is reflected in the syntax of references, the codes which uniquely identify these entities. These reference codes are stored along with their outlines in OpenStreetMap from which the data is obtained, using the property ("tag") ref.

References derive originally from University Estates Department property codes. These do not include college properties, so the numbering scheme has been extended to include these, and did not originally have any concept of subsites.

These property codes comprise an upper case letter which identifies a site followed by three digits identifying the building. For example M039 is the Cockcroft Building on the New Museums Site (M). (Estates did use an earlier numbering scheme which can be seen on the white sign boards at many entrances to the central sites. However these were abandoned in favour of this more regular scheme, and the sign boards have just not been updated).

Sometimes it is useful to represent an "Estates" building as more than one building, either because it actually is more than one (usually abutting) physical structure, or a code has been used to cover a group of not-very-distinct buildings, as in some of the farms, or it is useful to break up a large building into pieces where it is occupied in distinct parts (the Austin Robinson Building on the Sidgwick Site for example). These are represented by adding a period and another number to the reference (a decimal part, if you like). For example, the southern part of the Austin Robinson Building (the bit with the Sidgwick Buttery) is S012.3

Entrances are then represented by the building (for doors) or site (for gates etc) by the building or site code followed by a dash and one or more upper case letters. For example S012.3-A

Subsites are formed by following the site code with a slash and some more upper case letters. For example L/MATHS is the group of buildings and grounds of the Centre for Mathematical Studies.

Colleges follow the same pattern. Their codes for their main sites are their sub-domain names in upper case. For example CLARE for Clare College. Outliers are just like subsites, hence CLARE/MEM is Clare's Memorial Court property. Note that LUCY-CAV is unusual, being the only one with a dash in the code, so if you are parsing references using regular expressions, you need to allow for this.

Finally, college staircases, though individually part of particular buildings, are actually represented college-wide. Hence they are subiordinate to college sites and subsites, and their letter is separated from the site code by two dashes. Thus DOW--P is Downing's P staircase, which happens to be in the East Range though there is nothing to tell you that.

In summary

If X stands for one or more upper case letters, nnn for three digits and n for digits in general,

sites/colleges:  X  
subsites:  X/X  
site and subsite entrances:  X-X  X/X-X  
buildings:  Xnnn  X/Xnnn  
sub-buildings:  Xnnn.n  X/Xnnn.n  
building entrances:  Xnnn-X  Xnnn.n-X  X/Xnnn.n-X  X/Xnnn.n-X  
college staircases:  X--X  X/X--X  

Reference browser

For casual use to determine a reference, and for illustration of the API, there is a live reference hierarchy browser at

 http://map.cam.ac.uk/refbrowser/

This uses exactly the API wildcard requests as shown below.

Wildcards

You can ask for the descendants of a referenced item using an asterisk as a wildcard in place of the relevant piece of the reference.

There can only be one wildcard per ref. Also, it is not a general regular expression: a wildcard matches the whole of one piece, i.e. X, nnn or n above.

A single asterisk provides a starting point in the absence of any other, providing all the top-level sites and colleges, thus (using the API):

 http://map.cam.ac.uk/v6.json?ref=*

This pattern, like that for subsites below, also yields a few objects of type virtualsite, which are just like site except that they have no location information associated with them. Looking up their ref verbatim will yield no results. They are provided so that the complete set of prefix letters is available as a starting point. One of these is a grouping for non-university premises, with ref 'EXT'.

Furthermore, a Cambridge Biomedical Campus site object is included with site code 'H', which is a non-university site. Both 'H' and 'EXT' include a nonuniversity boolean member to distinguish them (use to colour them differently in the University map).

Given a particular site, CLARE say (obtained from the result of the above) one can then obtain all its subsites (if any), thus:

 http://map.cam.ac.uk/v6.json?ref=CLARE/*

Note that buildings of a site or subsite yields sub-buildings as well, because they aren't actually subdivisions, thus:

 http://map.cam.ac.uk/v6.json?ref=S*

includes S013.3 (as in the example above). However, one can also obtain the sub-buildings of a building code even if the building that would be represented with that code does not actually exist. Hence:

 http://map.cam.ac.uk/v6.json?ref=S013.*

This is useful in circumstances where you have the original property code but don't know whether it is divided up or not in the map. This will be useful in those circumstances.

 http://map.cam.ac.uk/v6.json?ref=SO13|S013.*

All the staircases at Clare College (main site only):

 http://map.cam.ac.uk/v6.json?ref=CLARE--*

and at Memorial Court:

 http://map.cam.ac.uk/v6.json?ref=CLARE/MEM--*

Results

The results from wildcard requests are just like those for any other request, namely an array of JSON objects, each representing the properties of the items yielded. Of particular note for geographic entities is their full reference and their location as latitude and longitude. Complete details are shown in the main main API documentation.

However, results for wildcarded references are excerpted entities, that is they do not contain full details of further hierarchy, such as occupants of buildings. Omitted elements for excerpts are listed with an asterisk in the main API documentation.

Combining patterns

As with non-wildcard references, several can be requested at once, separating them with a vertical bar. Therefore, all entrances of M031.1, M031.2 and M031.3 can be obtained thus:

 http://map.cam.ac.uk/v6.json?ref=M031.1-*|M031.2-*|M031.3-*

Note that you can't use ref=M031.*-* as you can only have one wildcard per reference.

Non university premises

Non-university premises often do not have standard University property codes, for obvious reasons. When they do, however, it is provided in OpenStreetMap by the ref:university_of_cambridge tag rather than just ref. These may be common university estate references where a building is owned by the University but let to or used by a third party; others are grouped into the virtual site with reference EXT (or for Addenbrooke's/Cambridge Biomedical Campus buildings etc, H).

Those that do have a reference are included in the general site/sub-site/building scheme and distinguished by a nonuniversity boolean member. Those that don't are objects of their own nonuniversity type.

(Note: the previous clumsy scheme using operators, colons and names has been removed).

Other starting points

As well as listing everything from the top or searching by name to obtain a reference, there are three other options if you don't know a reference:

  • When you ask for institutions, their locations and (main) entrances (both provided in the address info elements) contain references to the buildings and/or sites they occupy and the main entrances to get there. These can be followed up with a ref query to obtain more detail or a wildcard ref query to obtain subordinates.
  • By bounding box. Using a 'bb' query, one can obtain all institutions within an area, and these can be filtered by institution class as in filter=academic|nonacademic. However, it is also possible to use filters for site (which includes college sites, as opposed to college institutions, and includes subsites), building and entrance within an area. When qualify with any of these, institutions are not also returned unless you also explicitly filter for them. Thus filter=building only yields buildings. The centroid of buildings and sites must lie within the bounding box for them to be located, except that when requesting sites, if any main entrance of the site (not its buildings) falls within the box, the site is found.

    For example, this provides all of the buildings in and around the New Museums Site:
 http://map.cam.ac.uk/v6.json?bb=52.2021,0.1184,52.2047,0.1218&filter=building
  • For college staircases, you can guess! The college code is its upper case sub domain and the staircase letter is used in the reference code. So if you want staircase P in Downing, it is easy to ask for ref=DOW--P

Reference table

The following table also lists the main top-level codes, for reference. However, don't rely on this for a complete set, as new ones may be added.

code description notes
A Old Schools area virtual site: there is no site called 'A' but the buildings in this area are coded Annn
B Silver Street/Mill Lane Site
C Scroope Terrace area virtual site: buildings in this area are coded Cnnn and there are several subsites C/X
CUP Cambridge University Press CUP is treated as part of the University for the purposes of the map
D Downing Site
E Old Addenbrooke's Site
EXT "external" virtual, nonuniversity site to group non-university (and non-hospital) buildings conveniently
F "farms" includes buildings like the Agronomy Unit
H "hospital", the Cambridge Biomedical Campus the site is nonuniversity, but University premises within it are prefixed H in the usual way
K north city virtual site
L south city virtual site
M New Museums Site
R Mullard Radio Astronomy Observatory (MRAO)
S Sidgwick Site as well as the site, there are numerous outlying buildings to the west of Cambridge prefixed with S and a number of subsites (e.g. S/MATHS)
T Madingley Rise Site
W West Cambridge Site
The colleges
CAI Gonville & Caius College
CATHS St Catharine's College
CHRISTS Christ's College
CHU Churchill College
CLARE Clare College
CLAREHALL Clare Hall
CORPUS Corpus Christi College
DAR Darwin College
DOW Downing College
EMMA Emmanuel College
FITZ Fitzwilliam College
GIRTON Girton College
HOMERTON Homerton College
HUGHES Hughes Hall
JESUS Jesus College
JOH St John's College
KINGS King's College
LUCY-CAV Lucy Cavendish College
MAGD Magdalene College
MURRAYEDWARDS   Murray Edwards College
NEWN Newnham College
PEM Pembroke College
PET Peterhouse
QUEENS Queens' College
ROBINSON Robinson College
SEL Selwyn College
SID Sidney Sussex College
STEDMUNDS St Edmund's College
TRIN Trinity College
TRINH Trinity Hall
WOLFSON Wolfson College