Geospatial Data

On Key supports the attachment of geographical data to resources like Assets, Sites, Work Orders, Work Progress Log entries and more. The geographical data are attached to these resources using a GeographicExtension. The Location property on the GeographicExtension represents the geographical data and is captured and represented using the GeoJSON geospatial data interchange format.

GeoJSON is a geospatial data interchange format based on JavaScript Object Notation (JSON). It defines several types of JSON objects and the manner in which they are combined to represent data about geographic features, their properties, and their spatial extents. GeoJSON uses a geographic coordinate reference system, World Geodetic System 1984, and units of decimal degrees. Source

Spatially enabled resources can also capture the following properties on the GeographicExtension.

Property	Data Type	Purpose	Example
ReferenceEntityId	int64	Id for reference entity	100230300
ReferenceEntityType	enum	Type of reference entity	RegularAsset
StartPosition	decimal	Start offset from the reference entity	45
EndPosition	decimal	End offset from the reference entity	50
Length	decimal	Length	5
UnitOfMeasurement	int64	Unit of measurement reference id	km

The following schematic gives a high-level overview of the GeographicExtension and its associated geometry data.

A Geometry object represents points, curves, and surfaces in coordinate space. A Geometry object has a coordinates member that is an array. The structure and elements within this array is determined by the type of geometry object. A Position is the base geometry construct and represents an array of numbers. The first two elements are longitude and latitude and altitude/elevation may be included as a third, optional element.

Note

Altitude/elevation is not supported as On Key stores data as a geography type using PostGIS

The following sample request illustrates how to update the location for a Site using a Point geometry object:

curl -v -X PATCH https://{server}/api/tenants/{client}/{connection}/modules/gen/sites/50000120 \
-H 'Content-Type:application/vnd.onkey.entitypatch+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
        "version" : 1
        "operations": [
          {
            "path": "geographicLocation",
            "value": {
              "type": "FeatureCollection",
              "features": [
                {
                  "type": "Feature",
                  "properties": {},
                  "geometry": {
                    "coordinates": [
                      18.419494457226165,
                      -33.930080393423616
                    ],
                    "type": "Point"
                  }
                }
              ]
            }  
          }
        ]
    }'

Geometry Elements

The following sections give an overview with some sample json payloads for the different GeoJSON geometry objects supported by On Key. These geometry objects can be used to set the geographicLocation for any spatially enabled resource.

Point

A Point represents a single position.

Note

Altitude/elevation is not supported as On Key stores data as a geography type using PostGIS.

{
  "type": "Point",
  "coordinates": [ 100.0, 0.0 ]
}

MultiPoint

A MultiPoint represents an array of positions.

{
  "type": "MultiPoint",
  "coordinates": [
    [ 137.2, -32 ],
    [ 133.1, -30 ]
  ]
}

LineString

A LineString represents an array of two or more positions.

{
  "type": "LineString",
  "coordinates": [
    [ 33.959152462974146, -7.575887340582398 ],
    [ 33.85446153539874, -7.729561092279411 ],
    [ 33.850151476073705, -7.811936639038024 ],
    [ 33.62210683122379, -7.844646602233297 ]
  ]
}

MultiLineString

A MultiLineString represents an array of LineString coordinate arrays.

{
  "type": "MultiLineString",
  "coordinates": [ 
    [
      [ 33.959152462974146, -7.575887340582398 ],
      [ 33.85446153539874, -7.729561092279411 ],
      [ 33.850151476073705, -7.811936639038024 ],
      [ 33.62210683122379, -7.844646602233297 ]
    ],
    [
      [ 33.67484705357052, -7.269814784860827 ],
      [ 33.85719148627609, -7.326783112833738 ],
      [ 33.91763973774499, -7.333937486129514 ],
      [ 34.0584746845027, -7.39663911226522 ]
    ]    
  ]
}

Polygon

A Polygon represents a closed LineString of four or more positions called a linear ring.

• The first and last positions of the linear ring must be identical values.
• The first, exterior linear ring follows the right-hand (i.e. counterclockwise) rule for the area it bounds.
• Subsequent optional, interior linear rings (holes) follow the clockwise rule for the areas they bound.

{ 
  "type": "Polygon",
  "coordinates": [
    [
      [
        [ 25, -23 ],
        [ 25, -28 ],
        [ 30, -28 ],
        [ 30, -23 ],
        [ 25, -23 ]
      ],
      [
        [ 26, -24],
        [ 27, -24],
        [ 27, -25],
        [ 26, -25],
        [ 26, -24]
      ],
      [
        [ 28, -26 ],
        [ 28, -25 ],
        [ 29, -25 ],
        [ 29, -26 ],
        [ 28, -26 ]
      ]
    ]
  ]
}

MultiPolygon

A MultiPolygon represents an array of Polygon coordinate arrays.

{
  "type": "MultiPolygon",
  "coordinates": [
    [
      [
        [ 25, -23 ],
        [ 25, -28 ],
        [ 30, -28 ],
        [ 30, -23 ],
        [ 25, -23 ]
      ],
      [
        [ 26, -24],
        [ 27, -24],
        [ 27, -25],
        [ 26, -25],
        [ 26, -24]         
      ],
      [
        [ 28, -26 ],
        [ 28, -25 ],
        [ 29, -25 ],
        [ 29, -26 ],        
        [ 28, -26 ]
      ]
    ],
    [
      [
        [ 28.5, -28.2 ],
        [ 25.1, -30 ],
        [ 30.2, -31.2 ],
        [ 28.5, -28.2 ]
      ]
    ]
  ]
}

Feature

A Feature represents a spatially bounded object and wraps any of the above-mentioned geometry objects.

Note

The bbox and properties fields of a Feature is currently ignored by On Key.

{
  "type": "Feature",
  "properties": {},
  "geometry": {
    "coordinates": [
      18.419494457226165,
      -33.930080393423616
    ],
    "type": "Point"
  }
}

Feature Collection

A Feature Collection represents an array of Feature objects.

Note

A FeatureCollection with more than one Feature array element is currently not supported by On Key.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "coordinates": [
          18.419494457226165,
          -33.930080393423616
        ],
        "type": "Point"
      }
    }
  ]
}