Skip to content

API_Get

Jump to bottom
Andre Pawlowski edited this page Jun 30, 2019 · 4 revisions

API: Get

In this document the API to get GPS data from the server is explained. If you host the server yourself, it is reachable via the get.php file. If you are using the ChasR service, it is reachable via https://alertr.de/chasr/get.php.

Table of Contents

Authentication

Each API request requires you to authenticate yourself. The authentication can be done in two ways: send user credentials as HTTP POST parameter or send the session ID with your cookie.

When sending the user credentials as HTTP POST parameter, they have to be provided as the variables user and password. An example looks like the following:

HTTP POST data:
user=MyUsername&password=MySecretPassword

After authenticating via HTTP POST parameter, the server will send you a session ID in a cookie. With the help of this session ID, you can now authenticate without user credentials by just providing the session ID in your cookie.

However, if you do not want to authenticate with the session ID, you can always resort to providing the user credentials via HTTP POST parameter.

Get Devices

This request will return all devices stored for your user.

This API request needs to also provide an authentication of yourself. How you can authenticate yourself is described in the Authentication section.

The request contains the following HTTP GET parameters:

  • mode has to be provided with the value devices in order to return a list of all stored devices for the authenticated user.

The response will be provided in JSON format. The code field gives the error code of the request. The different error codes are explained on the Error Codes page. The data field contains a dictionary of the requested data. The requested data consists of the following fields:

The device field contains an array of the existing devices. Each device contains the following fields:

  • device_name: The name of the device.

The avail_slots field contains the number of device slots for your user on the server (meaning how many devices you can store on the server).

An example request and response looks like the following:

Request:
https://alertr.de/chasr/get.php?mode=devices

Response:
{
    "code": 0,
    "data": 
        {
            "devices":
                [
                    {
                        "device_name": "MyOwnDeviceName"
                    },
                    {
                        "device_name": "MyOtherDevice"
                    },
                    {
                        "device_name": "Car"
                    },
                    {
                        "device_name": "MyMobile"
                    }
                ],
            "avail_slots": 5,
        }
}

Get Last GPS Data

This request will return the last stored GPS data for the given device for your user.

This API request needs to also provide an authentication of yourself. How you can authenticate yourself is described in the Authentication section.

The request contains the following HTTP GET parameters:

  • mode has to be provided with the value last in order to return the last GPS position stored for the device for the authenticated user.
  • device has to be provided with the name of the device the GPS data is requested for.
  • limit can be provided to get more than just one GPS position for the device. The maximum amount of last GPS positions is set to 1000.

The response will be provided in JSON format. The code field gives the error code of the request. The different error codes are explained on the Error Codes page. The data field contains a dictionary of the requested data. The requested data consists of the following fields:

The locations field contains an array of the requested GPS data. Each GPS position contains the following fields:

  • device_name: The name of the device.
  • utctime: The UTC time of the GPS position (given as UNIX timestamp).
  • iv: The IV used to encrypt this GPS position in AES256-CBC.
  • lat: The encrypted latitude of the GPS position in PKCS#7 format as HEX string (exactly 32 characters).
  • lon: The encrypted longitude of the GPS position in PKCS#7 format as HEX string (exactly 32 characters).
  • alt: The encrypted altitude of the GPS position in PKCS#7 format as HEX string (exactly 32 characters).
  • speed: The encrypted speed of the GPS position in PKCS#7 format as HEX string (exactly 32 characters).
  • authtag: The HMAC-SHA256 build from the unencrypted values in the form HMAC(device_name | utctime | lat | lon | alt | speed) as HEX (exactly 64 characters).

An example request and response to obtain only the last GPS position for the device MyOwnDeviceName looks like the following:

Request:
https://alertr.de/chasr/get.php?mode=last&device=MyOwnDeviceName

Response:
{
    "code": 0,
    "data":
        {
            "locations":
                [
                    {
                        "device_name": "MyOwnDeviceName",
                        "utctime": 1524822825,
                        "iv": "c46632130fd2b9b60a74ff4efeb08192",
                        "lat": "7dc5139644f1a5e6ea1a60c1e17cfc40",
                        "lon": "8502f671fa44c53f9fa3d1e3d2d29bc5",
                        "alt": "da3e1be53dca26bb7cf4f8ba70994c77",
                        "speed": "16f7a101537587ee3fa483cbfc5ce2e1",
                        "authtag": "b894e85e75d280c4859c3d35016ab72d6d42a53d1c1928bf1a501cdbeb486380"
                    }
                ]
        }
}

An example request and response to obtain the last three GPS positions for the device MyOwnDeviceName looks like the following:

Request:
https://alertr.de/chasr/get.php?mode=last&device=MyOwnDeviceName&limit=3

Response:
{
    "code": 0,
    "data":
        {
            "locations":
                [
                    {
                        "device_name": "MyOwnDeviceName",
                        "utctime": 1524822825,
                        "iv": "c46632130fd2b9b60a74ff4efeb08192",
                        "lat": "7dc5139644f1a5e6ea1a60c1e17cfc40",
                        "lon": "8502f671fa44c53f9fa3d1e3d2d29bc5",
                        "alt": "da3e1be53dca26bb7cf4f8ba70994c77",
                        "speed": "16f7a101537587ee3fa483cbfc5ce2e1",
                        "authtag": "b894e85e75d280c4859c3d35016ab72d6d42a53d1c1928bf1a501cdbeb486380"
                    },
                    {
                        "device_name": "MyOwnDeviceName",
                        "utctime": 1524822765,
                        "iv":" 5cc356d00b2429c1b8983dc7606cb435",
                        "lat": "f27bddaa767e56775e2e182c6faf8da6",
                        "lon": "cdd79799211521daab9c350074fa0066",
                        "alt": "b33ec6a9a3d5e22e0832a01f19d19d65",
                        "speed": "81b009ef1aeeebf5f723f417877b4ca5",
                        "authtag": "c18db735bfad105500290ed4d6ae0e759f7b04d2efdc77e8b1a68e6faf2759b3"
                    },
                    {
                        "device_name":"MyOwnDeviceName",
                        "utctime": 1524822761,
                        "iv": "1c149e4cc2a244a4a51055e011171d15",
                        "lat": "447cbbf53d441a433172328b84340215",
                        "lon": "0664951c3adcd34976fabc01d2d6cccf",
                        "alt": "5faf7a9247e3329e269c83643a83d097",
                        "speed": "df9af0164699861369dda09124593d5d",
                        "authtag": "255d242ce84f1e6b63a36b5580da2d3e8cd3012ee4b91f427f40269d998d4db5"
                    }
                ]
        }
}

Get GPS Data

This request will return the stored GPS data in a given time frame for the given device for your user.

This API request needs to also provide an authentication of yourself. How you can authenticate yourself is described in the Authentication section.

The request contains the following HTTP GET parameters:

  • mode has to be provided with the value view in order to return the GPS position stored for the device for the authenticated user.

  • device has to be provided with the name of the device the GPS data is requested for.

  • start has to be provided as the start of the time frame the GPS data is requested for. It has to contain the UTC time given as UNIX timestamp.

  • end has to be provided as the end of the time frame the GPS data is requested for. It has to contain the UTC time given as UNIX timestamp.

The response will be provided in JSON format. The code field gives the error code of the request. The different error codes are explained on the Error Codes page. The data field contains a dictionary of the requested data. The requested data consists of the following fields:

The locations field contains an array of the requested GPS data. Each GPS position contains the following fields:

  • device_name: The name of the device.
  • utctime: The UTC time of the GPS position (given as UNIX timestamp).
  • iv: The IV used to encrypt this GPS position in AES256-CBC.
  • lat: The encrypted latitude of the GPS position in PKCS#7 format as HEX string (exactly 32 characters).
  • lon: The encrypted longitude of the GPS position in PKCS#7 format as HEX string (exactly 32 characters).
  • alt: The encrypted altitude of the GPS position in PKCS#7 format as HEX string (exactly 32 characters).
  • speed: The encrypted speed of the GPS position in PKCS#7 format as HEX string (exactly 32 characters).
  • authtag: The HMAC-SHA256 build from the unencrypted values in the form HMAC(device_name | utctime | lat | lon | alt | speed) as HEX (exactly 64 characters).

An example request and response to obtain the GPS positions stored for the device MyOwnDeviceName from 5th of May 2018 20:00:00 until 6th of May 2018 15:00:00 looks like the following:

Request:
https://alertr.de/chasr/get.php?mode=view&device=MyOwnDeviceName&start=1525550400&end=1525618800

Response:
{
    "code": 0,
    "data":
        {
            "locations":
                [
                    {
                        "device_name": "MyOwnDeviceName",
                        "utctime": 1525550440,
                        "iv": "c46632130fd2b9b60a74ff4efeb08192",
                        "lat": "7dc5139644f1a5e6ea1a60c1e17cfc40",
                        "lon": "8502f671fa44c53f9fa3d1e3d2d29bc5",
                        "alt": "da3e1be53dca26bb7cf4f8ba70994c77",
                        "speed": "16f7a101537587ee3fa483cbfc5ce2e1",
                        "authtag": "b894e85e75d280c4859c3d35016ab72d6d42a53d1c1928bf1a501cdbeb486380"
                    },
                    {
                        "device_name": "MyOwnDeviceName",
                        "utctime": 1525550445,
                        "iv":" 5cc356d00b2429c1b8983dc7606cb435",
                        "lat": "f27bddaa767e56775e2e182c6faf8da6",
                        "lon": "cdd79799211521daab9c350074fa0066",
                        "alt": "b33ec6a9a3d5e22e0832a01f19d19d65",
                        "speed": "81b009ef1aeeebf5f723f417877b4ca5",
                        "authtag": "c18db735bfad105500290ed4d6ae0e759f7b04d2efdc77e8b1a68e6faf2759b3"
                    },

                    [...]

                    {
                        "device_name":"MyOwnDeviceName",
                        "utctime": 1525618651,
                        "iv": "1c149e4cc2a244a4a51055e011171d15",
                        "lat": "447cbbf53d441a433172328b84340215",
                        "lon": "0664951c3adcd34976fabc01d2d6cccf",
                        "alt": "5faf7a9247e3329e269c83643a83d097",
                        "speed": "df9af0164699861369dda09124593d5d",
                        "authtag": "255d242ce84f1e6b63a36b5580da2d3e8cd3012ee4b91f427f40269d998d4db5"
                    }
                ]
        }
}
Clone this wiki locally