Format for locational information

[SiBell]

Many resources have a location, e.g. the location an observation was made or the location of a platform.

It makes sense to use a common format for presenting this location information.

Given that our API's serve JSON data, GeoJSON is the obviously candidate.

Here's my suggestion for how to do this.

Let's say a user requests a platform, e.g.

GET /platforms/building-1

The response might look like this:

{
  "@context": ["https://api.urbanobs.com/context/platform.jsonld"],
  "@id": "building-1",
  "name": "Building 1",
  "location": {
     "id": "some-location-id-perhaps-a-uuid",
     "type": "Feature",
     "geometry": {
       "type": "Polygon",
       "coordinates": [
         [
           [100.0, 0.0],
           [101.0, 0.0],
           [101.0, 1.0],
           [100.0, 1.0],
           [100.0, 0.0]
         ]
        ]
     },
    "properties": {
      "validAt": "2020-04-14T16:22:28.234Z"
    }
  },
  "centroid": {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [100.5, 0.5]
    }
  } 
}

Key points:

• In this example I've added location and centroid properties to the platform object. Both these location and centroid objects are valid GeoJSON Feature Objects.
• Not every resource can be represented by a Point, e.g. the building in this example is represented as a Polygon. However, in some circumstances, e.g. simple front-end applications, it may not be possible to display complex shapes such as polygons, and therefore an optional centroid object can be provided as well. I'd say we leave it up to the individual observatories to decide how best to calculate this (there's a few ways of doing this, some listed here).
• GeoJSON permits, and encourages, the presence of an id. We need to decide how to use this. The GeoJSON docs imply it would be the id of the platform, and this would certainly make sense were the Feature Object served as part of a Feature Collection of platforms. However in my mind it should be an id that represents that unique location. E.g. if you make lots of observations at the exact same location, then they would all have the same location id.
• Individual observatories may wish to add additional information about the location. This would go in the properties object. In my example I've added the time the location was valid at.

While it make sense for Platforms to have geometry types other than Point, we'd need to decide if this is also the case for Observations. If they'll only ever be Points then we probably don't want to bother with the centroid object for these. I guess you could argue that a rainfall radar image is an observation, which is a circle km's across rather than a point.

[EttoreHector]

location seems to imply a logical unit (a building, a lamp-post, a street, etc.). And the GeoJSON approach to location seem to suggest that these locations are worth their own representation in the database (with an id, a geometry, etc.). However often times you happen to locate a sensing device on a lamppost that does not have a specific significance per se. In fact, after a while you may want to move your device to a a lamp-post close by (just across the street) for some reason. Also that lamp-post my not be used any more to host any other device in the future or by any other deployment.

I guess in this case you would just avoid using the id property?

[SiBell]

So yes in my example the location is a "logical unit", the location of an actual "thing". However, as you say, there will be plenty of occasions where the location can't be easily linked to a "thing".

For example if you have a mobile Air Quality van driving round making observations, the location assigned to the stream of observations will keep changing. Even in this scenario I'd argue that we should be assigning a random location id. Chances are you'll have multiple sensors reading different observable properties at the same time and would therefore inherit the same location from whatever GPS unit was hosted on the van. To me all these observations recorded at the same time should have the same location id. If you realised later that your GPS reading was erroneous, you could easily find all the observations with this id and update them.

My only worry with this approach is if GeoJSON plotting tools, that end-users might be using, throw errors when they see more than one feature object with the same id.

[birminghamurbanobservatory]

centroid and shape better keys?

[aarepuu]

On the third elevation parameter in the coordinates. My reading of the GeoJSON Spec, it seems that it is from the sea level or geoid. And if there is no elevation, then it's just local ground or sea level.

The coordinate reference system for all GeoJSON coordinates is a geographic coordinate reference system, using the World Geodetic System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units of decimal degrees. This is equivalent to the coordinate reference system identified by the Open Geospatial Consortium (OGC) URN urn:ogc:def:crs:OGC::CRS84. An OPTIONAL third-position element SHALL be the height in meters above or below the WGS 84 reference ellipsoid. In the absence of elevation values, applications sensitive to height or depth SHOULD interpret positions as being at local ground or sea level.

[birminghamurbanobservatory]

Following the technical call on the 21st of April the approach we're going for is that for resources that have a location we MUST provide a GeoJSON Feature Object with a key of centroid with a geometry type of "Point". To be a valid Feature Object it must have the following properties: type, geometry and properties. The properties object can be empty. There's the option to include an id too.

There's also the option to include another GeoJSON Feature Object with a key of shape, for those resources that aren't points, but more complicated features such as polygons or lines.

Here's an example of all this:

{
  "@context": ["https://api.urbanobs.com/context/platform.jsonld"],
  "@id": "building-1",
  "@type": "Platform",
  "name": "Building 1",
  "centroid": {
    "id": "optional-id-in-here",
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [100.5, 0.5]
    },
    "properties": {
      "someExtraPropertyIfRequired": "some value"
    }
  }, 
  "shape": {
     "id": "optional-id-in-here",
     "type": "Feature",
     "geometry": {
       "type": "Polygon",
       "coordinates": [
         [
           [100.0, 0.0],
           [101.0, 0.0],
           [101.0, 1.0],
           [100.0, 1.0],
           [100.0, 0.0]
         ]
        ]
     },
    "properties": {}
  }
}

This is an example of a Platform, but these centroid and shape objects would look much the same were they associated with an Observation instead. Especially given that many observations will inherit the location of whichever platform they taken from at the time. I'd imagine that very few Observations will need to have a shape object as well as a centroid, other than perhaps rainfall radar images, or satellite images, etc, for which we want to capture the spatial extent.

[birminghamurbanobservatory]

Regarding the height coordinate: yer it looks like we have an option here.

A height above local ground would certainly be far easier to specify rather than trying to work out the height above sea level for the given location first and then adding the height above local ground.

However a height above sea-level is useful in a few applications, e.g. normalising air temperatures or barometric pressure.

My preference would be that the third coordinate in the geometry array would be a height above local ground, but we could add a height above sea level (i.e. WGS 84 reference ellipsoid) in the properties object where required.