Geolocation API

The VAPIX® Geolocation API provides the information that makes it possible to use position and orientation data on an Axis device.

The Position API provides the information that makes it possible to set up and check the position of a device. Position is specified in latitude, longitude and a free text field. The latitude and longitude coordinates should be in the WGS-84 format. Supported formats are DD, DMS and DMM, however no conversions will be done. The output format is always the same as the input format.

Position API functions

Function	Usage
geolocation/set.cgi	Set position
geolocation/get.cgi	Get position

The Orientation API provides the information that makes it possible to set up and use the orientation capabilities of a device. Orientation is specified by a heading, installation height, tilt and a roll field. The output format is always the same as the input format.

Orientation API functions

Function	Description
geoorientation	Set and get the orientation.

Overview

The Position API consists of 2 interfaces. One is used to query for all the data and one for updating either some or all of the fields.

The Orientation API consists of 1 interface where get/set is chosen by the parameter action.

Identification

Position API

• Property: Properties.API.HTTP.Version=3
• Property: Properties.Geolocation.Geolocation=yes
• Property: Properties.Geolocation.Version=0.01
• Firmware: 6.25 and later

Orientation API

• Property: Properties.API.HTTP.Version=3
• Property: Properties.Geoorientation.Geoorientation=yes
• Property: Properties.Geoorientation.Version=0.01
• Firmware: 11.5 and later

Format

Annex H of the ISO-6709 standard is used to set and read geographical positions. ISO-6709 is an international standard that represents latitude, longitude and altitude for geographical point locations.

All of the device rotations described by the orientation CGI are extrinsic, which means that they are independently described.

Signs

• North latitude and East longitude are positive (+).
• South latitude and West longitude are negative (-).
• The values 0.0 0.0 (lat/long) are valid data for a device residing in the Gulf of Guinea. When no geographical position data is available, or the current data for a moving device is outdated, the parameter ValidPosition should be set to false. Meanwhile, ValidPosition should be true for valid geographical position data.

Unit types

There exists three types of representation for representing the position that is currently supported:

• DD - degrees
• DDMM - degrees/minutes
• DDMMSS - degrees/minutes/seconds

Degrees (DD)

The position is only given in whole and decimal degrees. The integer part is of fixed length, using 2 digits (-90 to +90 degrees) for latitude and 3 digits (-180 to +180 degrees) for longitude. The number of digits indicates the units, which means that leading zero(es) must be filled when necessary. The fractional part must have the appropriate number of digits to represent the required precision of the coordinate.

Example latitude

33.55555 to 33.55555 degrees
+33.5555 to 33.5555 degrees
-45.5555 to -45.5555 degrees
03.55555 to 3.55555 degrees

Example longitude

013.55555 to 13.55555 degrees
+013.5555 to 13.5555 degrees
-110.5555 to -110.5555 degrees
002.55555 to 2.55555 degrees

Degrees/Minutes (DDMM)

The position is given in whole degrees as well as whole and decimal minutes. The integer part is of a fixed length with 4 digits (-90 to +90 degrees and 0 to 60 minutes) for latitude and 5 digits (-180 to +180 degrees and 0 to 60 minutes) for longitude. The number of digits indicates the units, which means that leading zero(es) must be filled when necessary.

Example latitude

3312.55555 to 33 degrees, 12.55555 minutes
+3312.5555 to 33 degrees, 12.5555 minutes
-4512.5555 to -45 degrees 12.5555 minutes
0300.55555 to 3 degrees, 0.55555 minutes

Example longitude

01322.55555 to 13 degrees, 22.55555 minutes
+01322.5555 to 13 degrees, 22.5555 minutes
-11022.5555 to -110 degrees, 22.5555 minutes
00200.55555 to 2 degrees, 0.55555 minutes

Degrees/Minutes/Seconds (DDMMSS)

The position is given in whole degrees, whole minutes and decimal seconds. The integer part is of a fixed length at 6 digits (-90 to +90 degrees, 0 to 60 minutes and 0 to 60 seconds) for latitude and 7 digits (-180 to +180 degrees, 0 to 60 minutes and 0 to 60 seconds) for longitude. The number of digits indicates the units, which means that leading zero(es) must be filled when necessary.

Example latitude

223312.55555 to 22 degrees, 33 minutes, 12.55555 seconds
+223312.5555 to 22 degrees, 33 minutes, 12.5555 seconds
-334512.5555 to -33 degrees, 45 minutes, 12.5555 seconds
000300.55555 to 0 degrees, 3 minutes, 0.55555 seconds

Example longitude

0134422.55555 to 13 degrees, 44 minutes, 22.55555 seconds
+0134422.5555 to 13 degrees, 44 minutes, 22.5555 seconds
-1410022.5555 to -141 degrees, 0 minutes, 22.5555 seconds
0020500.55555 to 2 degrees, 5 minutes, 0.55555 seconds

Heading

The heading indicates the direction of the device in degrees and valid values are integers between 0 and 360 where 0 degrees corresponds to the North direction.

Example

heading=90 - the device is rotated 90 degrees from North and pointing East
heading=270 - the device is pointing West

When no valid heading data is available, or the heading data for a moving device has become outdated, the parameter ValidHeading should be set to false.

Installation height

Indicates the height, measured in meters, at which the device is installed relative to the floor.

Example

height=2.2 - the device is installed 2.2 meters above the floor.

Tilt

Defines the tilt angle (-180 to +180 degrees) which the device is pointing towards. A vector pointing down at the floor represents tilt zero. Moving the tilt in the positive orientation represents a movement towards the same direction as heading. A negative tilt rotates the vector in the contrary direction as the heading.

Example

Tilt=0 - the device is pointing perpendicular to the floor.
Tilt=90 - the device is pointing parallel to the floor towards the heading direction.
Tilt=-90 - the device is pointing parallel to the floor in the opposite direction from heading.

Roll

Defines the roll level (-180 to +180 degrees). A value of 0 represents a device perpendicular to gravity. Positive values represents a roll to the right and negative values a roll to the left.

Example

Roll=0 - the device is parallel to the floor.
Roll=180 - the device is upside down.
Roll=90 - the device is rolled 90 degrees to the right and is positioned perpendicular to the floor.

Common examples

Get complete position data

Use this example to locate the device as well as to get its position data in order to make a map for all installed devices.

http://myserver/axis-cgi/geolocation/get.cgi

1. Parse the response

<PositionResponse SchemaVersion="1.0">
  <Success>
    <GetSuccess>
      <Location>
        <Lat>51.0</Lat>
        <Lng>-0.1</Lng>
        <Heading>30</Heading>
      </Location>
      <Text>Free text</Text>
      <ValidPosition>true</ValidPosition>
      <ValidHeading>false</ValidHeading>
    </GetSuccess>
  </Success>
</PositionResponse>

Retrieve complete orientation data

This example will show you how to apply available orientation data. This include checking the device orientation to calculate depth in either the image or correlate a device image to a real world space.

http://myserver/axis-cgi/geoorientation/geoorientation.cgi?action=get

1. Parse the response.

<OrientationResponse SchemaVersion="1.0">
  <Success>
    <GetSuccess>
      <Tilt>70.0</Tilt>
      <InstallationHeight>3.2</InstallationHeight>
      <Heading>140.0</Heading>
      <ValidTilt>True</ValidTilt>
      <ValidInstallationHeight>True</ValidInstallationHeight>
      <ValidHeading>True</ValidHeading>
    </GetSuccess>
  </Success>
</OrientationResponse>

Set position

Use this example to get position data from an external source in order to set location data for a device. External sources include, but are not limited to, GPS and Mobile phones.

Set position using DD units

http://myserver/axis-cgi/geolocation/set.cgi?lat=51.1234&lng=013.1234&heading=30&text="freetext"

1. Receive response

<PositionResponse SchemaVersion="1.0">
  <Success>
    <GeneralSuccess/>
  </Success>
</PositionResponse>

Set position using DDMM units

http://myserver/axis-cgi/geolocation/set.cgi?lat=5112.3456&lng=01312.3456&heading=30&text="freetext"

1. Receive response

<PositionResponse SchemaVersion="1.0">
  <Success>
    <GeneralSuccess/>
  </Success>
</PositionResponse>

Set position using DDMMSS units

http://myserver/axis-cgi/geolocation/set.cgi?lat=511234.5678&lng=0131234.5678&heading=30&text="free text"

1. Receive response

<PositionResponse SchemaVersion="1.0">
  <Success>
    <GeneralSuccess/>
  </Success>
</PositionResponse>

Set location tag

Use this example to set location tags from an external source in order to distinguish between two devices in the same location but on different floors.

http://myserver/axis-cgi/geolocation/set.cgi?lat=51.0&lng=-0.1&text="floor 2"

1. Receive response

<PositionResponse SchemaVersion="1.0">
  <Success>
    <GeneralSuccess/>
  </Success>
</PositionResponse>

Set orientation

This example will show you how to set the orientation data on a device and improve image depth calculations.

http://myserver/axis-cgi/geoorientation/geoorientation.cgi?action=set&heading=30.0&inst_height=2.3&tilt=-80.0"

1. Parse the response.

<OrientationResponse SchemaVersion="1.0">
  <Success>
    <GeneralSuccess/>
  </Success>
</OrientationResponse>

API specification

position/get

Get position information.

Request

• Security level: Admin
• Method: GET/POST

http://<servername>/axis-cgi/geolocation/get.cgi

Return value - Success

Returns latitude, longitude and direction.

• HTTP Code: 200 OK

• Content-type

  application/xml

Response body syntax:

<PositionResponse SchemaVersion="1.0">
  <Success>
    <GetSuccess>
      <Location>
        <Lat>51.0</Lat>
        <Lng>-0.1</Lng>
        <Heading>30</Heading>
      </Location>
      <Text>Free text</Text>
      <ValidPosition>true</ValidPosition>
      <ValidHeading>true</ValidHeading>
    </GetSuccess>
  </Success>
</PositionResponse>

Return value - Error

0 and empty string are default values and will be returned if nothing is set.

position/set

Set new position information.

Request

• Security level: Admin
• Method: GET/POST

http://<servername>/axis-cgi/geolocation/set.cgi?<argument>=<data>[&<argument>=<data>[&...]]

Parameter	Description
lat=latitude	New value for latitude.
lng=longitude	New value for longitude.
text=text	New value for free text.

Return value - Success

• HTTP Code: 200 OK

• Content-type

  application/xml

Response body syntax:

<PositionResponse SchemaVersion="1.0">
  <Success>
    <GeneralSuccess/>
  </Success>
</PositionResponse>

Return value - Error

• HTTP Code: 200 OK

• Content-type

  application/xml

Response body syntax:

<PositionResponse SchemaVersion="1.0">
  <Error>
    <SetError>
      <ErrorCode>1</ErrorCode>
      <ErrorDescription>Invalid parameter</ErrorDescription>
      <ErrorCode>2</ErrorCode>
      <ErrorDescription>Invalid value</ErrorDescription>
      <ErrorCode>3</ErrorCode>
      <ErrorDescription>Internal Error</ErrorDescription>
    </SetError>
  </Error>
</PositionResponse>

orientation/get

Get orientation information.

Request

• Security level: Admin
• Method: GET/POST

http://<servername>/axis-cgi/geoorientation/geoorientation.cgi?action=get

Return value - Success

Returns tilt angle, installation height and heading.

• HTTP Code: 200 OK

• Content-type

  application/xml

Response body syntax:

<OrientationResponse SchemaVersion="1.0">
  <Success>
    <GetSuccess>
      <Tilt>60.0</Tilt>
      <InstallationHeight>2.2</InstallationHeight>
      <Heading>90.0</Heading>
      <ValidTilt>true</ValidTilt>
      <ValidInstallationHeight>true</ValidInstallationHeight>
      <ValidHeading>true</ValidHeading>
    </GetSuccess>
  </Success>
</OrientationResponse>

Return value - Error

0 and false are default values and will be returned if nothing is set.

orientation/set

Set new orientation information.

Request

• Security level: Admin
• Method: GET/POST

http://<servername>/axis-cgi/geoorientation/geoorientation.cgi?action=set&<argument>=<data>[&<argument>=<data>[&...]]

Parameter	Description
tilt=tilt	New value for tilt.
heading=heading	New value for heading.
inst_height=installation height	New value for installation height.

Return value - Success

• HTTP Code: 200 OK

• Content-type

  application/xml

Response body syntax:

<OrientationResponse SchemaVersion="1.0">
  <Success>
    <GeneralSuccess/>
  </Success>
</OrientationResponse>

Return value - Error

• HTTP Code: 200 OK

• Content-type

  application/xml

Response body syntax:

<OrientationResponse SchemaVersion="1.0">
  <Error>
    <SetError>
      <ErrorCode>1</ErrorCode>
      <ErrorDescription>Invalid parameter</ErrorDescription>
      <ErrorCode>2</ErrorCode>
      <ErrorDescription>Invalid value</ErrorDescription>
      <ErrorCode>3</ErrorCode>
      <ErrorDescription>Internal Error</ErrorDescription>
    </SetError>
  </Error>
</OrientationResponse>