Difference between revisions of "The Database API reference discovery"

From University Map Wiki
Jump to navigationJump to search
(Created page with "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. ==Introduction==...")
 
Line 16: Line 16:
  
 
==Geographical entity hierarchy==
 
==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)
 +
* building
 +
* entrance (to a building or to a site)
 +
* 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
 +
    |        |        |
 +
    |        |        |----- (building) entrance
 +
    |        |
 +
    |        |----- (site) entrance
 +
    |        |
 +
    |        |----- (staircase) entrance
 +
    |
 +
    |----- building/sub-building
 +
    |        |
 +
    |        |----- (building) entrance
 +
    |
 +
    |----- (site) entrance
 +
    |
 +
    |----- (staircase) entrance
 +
 +
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 store 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.
 +
 +
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
 +
 +
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].
 +
 +
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.
 +
 +
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===
 +
 +
If X stands for one or more upper case letters, nnn for three digits and n for digits in general,
 +
 +
<table>
 +
<tr><td>sites/colleges:&nbsp;&nbsp;</td><td>X&nbsp;&nbsp;</td><td></td></tr>
 +
<tr><td>subsites:&nbsp;&nbsp;</td><td>X/X&nbsp;&nbsp;</td><td></td></tr>
 +
<tr><td>site and subsite entrances:&nbsp;&nbsp;</td><td>X-X&nbsp;&nbsp;</td><td>X/X-X&nbsp;&nbsp;</td></tr>
 +
<tr><td>buildings:&nbsp;&nbsp;</td><td>Xnnn&nbsp;&nbsp;</td><td>X/Xnnn&nbsp;&nbsp;</td></tr>
 +
<tr><td>sub-buildings:&nbsp;&nbsp;</td><td>Xnnn.n&nbsp;&nbsp;</td><td>X/Xnnn.n&nbsp;&nbsp;</td></tr>
 +
<tr><td>building entrances:&nbsp;&nbsp;</td><td>Xnnn-X&nbsp;&nbsp;</td><td>Xnnn.n-X&nbsp;&nbsp;</td><td>X/Xnnn.n-X&nbsp;&nbsp;</td><td>X/Xnnn.n-X&nbsp;&nbsp;</td></tr>
 +
<tr><td>college staircases:&nbsp;&nbsp;</td><td>X--X&nbsp;&nbsp;</td><td>X/X--X&nbsp;&nbsp;</td></tr>
 +
</table>

Revision as of 16:35, 11 December 2012

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.

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

Therefore, the API also provides 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.

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)
  • building
  • entrance (to a building or to a site)
  • 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
    |        |        |
    |        |        |----- (building) entrance
    |        |
    |        |----- (site) entrance
    |        |
    |        |----- (staircase) entrance
    |
    |----- building/sub-building
    |        |
    |        |----- (building) entrance
    |
    |----- (site) entrance
    |
    |----- (staircase) entrance

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

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.

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 detail

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