NAV Navbar
shell
  • Introduction
  • Authentication
  • Devices
  • Errors
  • Introduction

    Welcome to the marXact UNI Cloud API! You can use our API to access UNI Cloud API API endpoints, which can get information of the UNI-GR1 GNSS Receiver.

    We have language bindings in Shell! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    Authentication

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl --request POST \
      --url https://login.marxact.com/connect/token \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data 'grant_type=password&client_id=<client_id>&client_secret=<client_secret>&username=<username>&password=<password>&scope=offline_access role cloudapi'
    

    The above command returns JSON structured like this:

    {
        "access_token": "access_token",
        "expires_in": 86400,
        "token_type": "Bearer",
        "refresh_token": "refresh_token"
    }
    

    To refresh an access_token, use this code:

    # With shell, you can just pass the correct header with each request
    curl --request POST \
      --url https://login.marxact.com/connect/token \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data 'grant_type=refresh_token&client_id=<client_id>&client_secret=<client_secret>&refresh_token=<refresh_token>'
    

    The above command returns JSON structured like this:

    {
        "id_token": "id_token",
        "access_token": "access_token",
        "expires_in": 86400,
        "token_type": "Bearer",
        "refresh_token": "refresh_token"
    }
    

    marXact UNI Cloud API expects for the Access Token to be included in all API requests to the server in a header that looks like the following:

    Authorization: Bearer <access_token>

    Devices

    Get All Devices

    curl "https://api.marxact.com/v1/devices"
      -H "Authorization: Bearer <access_token>"
    

    The above command returns JSON structured like this:

    [
      {
        "id": 1,
        "name": "DeviceName1",
        "positioningMode": "SINGLE",
        "differential": {
          "date": "2018-06-19T12:37:59Z",
          "baseId": "ReferenceStationId"
        },
        "location": {
          "date": "2018-06-19T12:37:59Z",
          "latitude": 52.21421678733,
          "latitudeDeviation": 4.1945,
          "longitude": 5.14718163569,
          "longitudeDeviation": 2.2603,
          "height": 4.5514,
          "heightDeviation": 3.2624,
          "undulation": 43.3835,
          "satellitesTracked": 13,
          "satellitesInUse": 8,
          "solutionAge": 0,
          "solutionStatus": "SINGLE"
        },
        "speed": {
          "date": "2018-06-19T12:37:59Z",
          "horizontalSpeed": 0.0381,
          "direction": 85.264076,
          "verticalSpeed": -0.0199
        },
        "info": {
          "date": "2018-06-19T12:37:59Z",
          "batteryPercentage": 50,
          "elevationX": 437,
          "elevationY": 437,
          "elevationZ": 0
        }
      },
      {
        "id": 2,
        "name": "DeviceName2",
        "positioningMode": "RTK_AUTO",
        "differential": null,
        "location": null,
        "speed": null,
        "info": null
      }
    ]
    

    Get a Specific Device

    curl "https://api.marxact.com/v1/devices/1"
      -H "Authorization: Bearer <access_token>"
    

    The above command returns JSON structured like this:

    {
      "id": 1,
      "name": "DeviceName1",
      "positioningMode": "SINGLE",
      "differential": {
        "date": "2018-06-19T12:37:59Z",
        "baseId": "ReferenceStationId",
        "differentialAge": 0
      },
      "location": {
        "date": "2018-06-19T12:37:59Z",
        "latitude": 52.21421678733,
        "latitudeDeviation": 4.1945,
        "longitude": 5.14718163569,
        "longitudeDeviation": 2.2603,
        "height": 4.5514,
        "heightDeviation": 3.2624,
        "undulation": 43.3835,
        "satellitesTracked": 13,
        "satellitesInUse": 8,
        "solutionAge": 0,
        "solutionStatus": "SINGLE"
      },
      "speed": {
        "date": "2018-06-19T12:37:59Z",
        "horizontalSpeed": 0.0381,
        "direction": 85.264076,
        "verticalSpeed": -0.0199
      },
      "info": {
        "date": "2018-06-19T12:37:59Z",
        "batteryPercentage": 50,
        "elevationX": 437,
        "elevationY": 437,
        "elevationZ": 0
      }
    }
    

    Get Specific Device Differential Data

    curl "https://api.marxact.com/v1/devices/1/differential"
      -H "Authorization: Bearer <access_token>"
    

    The above command returns JSON structured like this:

    {
        "date": "2018-06-19T12:37:59Z",
        "baseId": "ReferenceStationId",
        "differentialAge": 0
    }
    

    Get Specific Device Information Data

    curl "https://api.marxact.com/v1/devices/1/info"
      -H "Authorization: Bearer <access_token>"
    

    The above command returns JSON structured like this:

    {
      "date": "2018-06-19T12:37:59Z",
      "batteryPercentage": 50,
      "elevationX": 437,
      "elevationY": 437,
      "elevationZ": 0
    }
    

    Get Specific Device Location Data

    curl "https://api.marxact.com/v1/devices/1/location"
      -H "Authorization: Bearer <access_token>"
    

    The above command returns JSON structured like this:

    {
      "date": "2018-06-19T12:37:59Z",
      "latitude": 52.21421678733,
      "latitudeDeviation": 4.1945,
      "longitude": 5.14718163569,
      "longitudeDeviation": 2.2603,
      "height": 4.5514,
      "heightDeviation": 3.2624,
      "undulation": 43.3835,
      "satellitesTracked": 13,
      "satellitesInUse": 8,
      "solutionAge": 0,
      "solutionStatus": "SINGLE"
    }
    

    Get Specific Device Speed Data

    curl "https://api.marxact.com/v1/devices/1/speed"
      -H "Authorization: Bearer <access_token>"
    

    The above command returns JSON structured like this:

    {
      "date": "2018-06-19T12:37:59Z",
      "horizontalSpeed": 0.0381,
      "direction": 85.264076,
      "verticalSpeed": -0.0199
    }
    

    Errors

    The marXact UNI Cloud API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your Access Token is wrong.
    403 Forbidden -- The requested is hidden for the user role.
    404 Not Found -- The specified url could not be found.
    405 Method Not Allowed -- You tried to access with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    410 Gone -- The requested has been removed from our servers.
    418 I'm a teapot.
    429 Too Many Requests -- You're requesting too many! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.