The Database API v6 changes

This document summarises the changes between the now withdrawn version 5 (old complete documentation for version 5) and version 6 (full documentation for version 6) of the University Map Database API.

Version 5 (v5.json) is no longer supported. It returns an HTTP 410 error. Version 6 is provided through http://map.cam.ac.uk/v6.json

Changes

Subsections

old

In v5, institution info objects indicated that they should be presented in some related group (as for example the phone, fax and email of a part or function of an institution, like the Box Office details for the ADC theatre, separate form the administrative details), by a repeated (explicit or implicit with a ditto mark) role element.

new

In v6 this is now explicit using the subsection and subsection-end elements within the info array. The string value of subsection represents a sub-heading for the subsection.

A subsection is ended by the start of another subsection, and explicit subsection-end element, or the end of the info object.

As well as making the structure much more explicit, this also allows the role of individual elements within a subsection to be included.

For example:

 [
   {
     "type": "institution",
     "inst": "adcth",
     "name": "ADC Theatre",
     "role": "nonacademic",
     "info": [ 
       {
         "type": "address",
         "address": [
           { "type": "street", "street": "Park Street" },
           { "type": "place", "place": "Cambridge" },
           { "type": "postcode", "postcode": "CB5 8AS" },
           { "type": "location", "location": { ... } }
         ]
       },
       { "type": "url", "url": "http:\/\/www.adctheatre.com\/" },
 
       { "type": "subsection", "subsection": "Box Office" },
       { "type": "phone", "phone": "+44 1223 300085" },
       { "type": "email", "email": "boxoffice@adctheatre.com" },
 
       { "type": "subsection", "subsection": "Administration" },
       { "type": "phone", "phone": "+44 1223 359547" },
       { "type": "email", "email": "info@adctheatre.com" },
       { "type": "subsection-end", "subsection-end": "" }
     ]
   }
 ]

Locations and entrances

old

In v5, the geographical locations and entrances of an institution were returned in the top level institution object as

 locations: [ ... ]
 entrances: [ ... ]

being arrays of location and entrance objects respectively. The relationship of a postal address (an info address element) was indicated in the address object by

 location: i

where i was the (1-based) index of the corresponding location in the locations array. This was cumbersome, error-prone, and did not relate entrances to locations other than by implication in the structure of their reference numbers.

new

In v6, location and entrance are removed from the top level institution object and subsumed into the address object. For example:

 [
   { "type": "institution",
     "inst": "asnc",
     "prefix": "Department of",
     "name": "Anglo-Saxon, Norse and Celtic",
     "sd": "asnc",
     "role": "academic",
     "info": [
       { "type": "address", "address": [
         { "type": "number", "number": "9" },
         { "type": "street", "street": "West Road" },
         { "type": "place", "place": "Cambridge" },
         { "type": "postcode", "postcode": "CB3 9DP" },
         { "type": "location",
           "location": {
             "type": "building", "ref": "S040", "name": "Faculty of English",
             "lat": 52.20246, "lon": 0.108541, "id": 26378099
           }
         },
         { "type": "entrance",
           "entrance": {
             "type": "entrance", "ref": "S040-A",
             "lat": 52.202422, "lon": 0.108616, "direction": -169,
             "user": "f", "primitive": "n", "id": 1487638771, "entrance": "main", "door": true
           }
         },
         ...
         ]
       },
       ...
     ]
   }
 ]

An address object has at most one location element, which is now a location object not a number, and if there is a location then zero or more entrance elements corresponding to that location. This means postal addresses are directly related to their geographical locations, and entrances directly tied to their corresponding locations.

There may be addresses with no location (either we do not know it, or there is a postal address, such as a PO Box, for correspondence only), and addresses with only a location (we do not know the postal address, or more commonly there is a single postal address and then other locations in separate "address" elements which are to be pinned on a map but which are not for postal correspondence.

Useful code

Though the relationship between addresses, locations and entrances is now explicitly shown, it is nevertheless still useful when processing locations to have them to hand in a single, iterable JavaScript object, rather than dispersed among the addresses.

The following JavaScript function may be useful in creating and caching such a structure. It puts the entrances of a location into the location object and retains an index to the address info object to which the location (and entrances) are related, and both returns and stores this in the top level institution object.

 function get_locations(ji) {
   if (! ji.locations) {
       ji.locations = [];
       if ("info" in ji) {
           for (var ii in ji.info) {
               var info = ji.info[ii];
               if (info.type != "address") { continue; }
               var icurloc = -1;
               for (var ia in info.address) {
                   var address = info.address[ia];
                   if (address.type == "location" && address.location != null) {
                       icurloc = ji.locations.push(address.location) - 1;
                       ji.locations[ji.locations.length-1].entrances = [];
                       ji.locations[ji.locations.length-1].iinfo = ii;
                   } else if (address.type == "entrance" && icurloc >= 0) {
                       ji.locations[icurloc].entrances.push(address.entrance);
                   }
               }
           }
       }
   }
   return ji.locations;
 }