< Back to API menu

New PPK survey

First, create the survey and the related rovers.

POST http://api.rinexlab.com/v1/ppk/surveys

The authentication token has to be included as a bearer token in the request headers.

With a JSON body containing the survey and rovers details. The rovers list must be a list even if there is only one of them. Please note that rovers must be all created here. You can't add one to the survey afterwards.

{
    "token": <ppk_token>,
    "datum": <datum>,
    "name": <survey_name>,
    "rovers": [
        {
            "antenna_height": <antenna_height>,
            "data_format": <data_format>,
            "mode": <mode>,
            "name": <rover_name>
        },
		..., # up to 4 rover objects
    ]
}

With :

  • ppk_token (str) : the PPK token you subscribed. It must be valid and have some remaining credits ;
  • datum (str) : the survey datum. Accepted values are etrf2000rgf93nad83, sirgas, rgr92, rgfg95, rgm04, rgaf09, rgspm06, etrf2014, itrf2014 ;
  • survey_name (str) : the name of the survey ; MUST be a unique value
  • antenna_height (float) : antenna height of the rover in meters ;
  • data_format (str) : format of the rover raw data. Accepted values are autoubx (Ublox / Emlid), lei (Leica Geosystems), tr (Trimble), sbf (Septentrio), rinex (RINEX) ;
  • mode (str) : positioning mode. Accepted values are kinematicstatic ;
  • rover_name (str) : name of the rover.

The maximum number of rovers is 4 per survey.

The server response is expected to be a code 201 with the following JSON content.

{
    "bases": [],
    "created_at": <creation_datetime>,
    "datum": <datum>,
    "id": <survey_id>,
    "name": <survey_name>,
    "rovers": [
        {
            "antenna_height": <antenna_height>,
            "data_format": <data_format>,
            "file": <rover_file>,
            "id": <rover_id>,
            "mode": <mode>,
            "name": <rover_name>,
            "results": <rover_results>,
            "status": <rover_status>
        }
    ]
}

With :

  • an empty bases list, as none has been submitted. The server will generate some virtual stations to compute the rover position.
  • creation_datetime (str) : time of creation, formatted in "%Y-%m-%d %H:%M:%S" ;
  • datum (str) : the survey datum ;
  • survey_id (int) : the unique ID of the survey ;
  • antenna_height (float) : antenna height of the rover in meters ;
  • data_format (str) : format of the rover raw data that is to be uploaded ;
  • file (str) : the URL of the raw data file - at this point it is empty because it has not been uploaded yet, see below ;
  • rover_id (int) : the unique ID of the rover ;
  • mode (str) : positioning mode ;
  • rover_name (str) : name of the rover ;
  • rover_results (str) : the URL of the results file - at this point it is empty because no process has been done yet ;
  • rover_status (int) : the status of the rover processing. Possible values are -1 (recorded without file yet), 0 (pending), 1 (processing), 2 (done), 3 (failed). 

Here is an example in Python 3.x

import requests

host = 'http://api.rinexlab.com'
version = 'v1'

auth_token = 'ey...Ugs' # token retrieved from the login process
ppk_token = 'jf8...12e' # PPK token you subscribed
datum = 'nad83'

r = requests.post(f'{host}/{version}/ppk/surveys',
	json={
		"token": ppk_token,
		"datum": datum,
		"name": "my new PPK survey",
		"rovers": [
			{
				"antenna_height": 0.0,
				"data_format": "auto",
				"mode": "kinematic",
				"name": "ROVER1"
			}
		]
	},
headers={'Authorization': f'Bearer {auth_token}'}
)
survey = r.json()
print(survey)

New PPK survey with your own base

Optionally you can create a survey with your own base. You have to add a "bases" key in the JSON body with the base object as a list.

{
    "token": <ppk_token>,
    "datum": <datum>,
    "name": <survey_name>,
	"bases": [
		{
			"antenna_height": <base_antenna_height>,
            "data_format": <base_data_format>,
            "coordinates": <base_coordinates>,
            "name": <base_name>
		}
	]
    "rovers": [
        {
            "antenna_height": <antenna_height>,
            "data_format": <data_format>,
            "mode": <mode>,
            "name": <rover_name>
        },
		..., # up to 4 rover objects
    ]
}

With the new parameters :

  • base_antenna_height (float) : antenna height of the base in meters ;
  • data_format (str) : format of the base raw data. Accepted values are autoubx (Ublox / Emlid), lei (Leica Geosystems), tr (Trimble), sbf (Septentrio), rinex (RINEX) ;
  • base_coordinates (str) : known coordinates of the base stations in the survey datum, formatted in a comma-separated string with "<latitude>,<longitude>,<height>". Latitude and longitude are in decimal degrees, and height is in meters. Be careful this is the ellipsoid height here, not a geoid height ;
  • base_name (str) : name of the base station.

Here is an an example of how to post a new survey with your own base in it in Python 3.x.

import requests

# API route
host = 'http://api.rinexlab.com'
version = 'v1'

# credentials
auth_token = 'ey...Ugs' # token retrieved from the login process
ppk_token = 'jf8...12e' # PPK token you subscribed

# survey info
datum = 'auto'
survey_name = 'my new PPK survey'

# base info
bases_json = [
	{
		'antenna_height': 0 # float in meters
		'coordinates': '48.23645,2.456188,154.963' # string with latitude, longitude in decimal degrees, and height in meters
		'data_format': 'auto', # see below for accepted values
		'name': 'BASE'
	}		
]

# rovers info
rovers_json = [
	{
		'antenna_height': 0.0,
		'data_format': 'auto',
		'mode': 'kinematic',
		'name': 'ROVER1'
	}
]

r = requests.post(f'{host}/{version}/ppk/surveys',
	json={
		'token': ppk_token,
		'datum': survey_datum,
		'name': survey_name,
		'bases': bases_json
		'rovers': rovers_json
	},
headers={'Authorization': f'Bearer {auth_token}'}
)
survey = r.json()
print(survey)

Add raw data files to the survey

At this point the survey object is created, but no process can be done. Upload the raw data file to each of the rover with a POST request. The data to upload have to be in the key called "file" in the form-data.

POST http://api.rinexlab.com/v1/ppk/surveys/<survey_id>/rovers/<rover_id>/file

The server response is expected to be a code 201 with the following JSON content. This is a rover object.

{
    "antenna_height": <antenna_height>,
    "data_format": <data_format>,
    "file": <rover_file>,
    "id": <rover_id>,
    "mode": <mode>,
    "name": <rover_name>,
    "results": <rover_results>,
    "status": 0
}

The same goes for the base station file if you posted the new survey with your own base.

POST http://api.rinexlab.com/v1/ppk/surveys/<survey_id>/bases/<base_id>/file

The server returns a base object.

{
    "antenna_height": <base_antenna_height>,
    "coordinates": <base_coordinates>,
    "data_format": <base_data_format>,
    "file": <base_file>,
    "id": <base_id>,
    "name": <base_name>
}

The process is started automatically as soon as a file has been uploaded for every rover of the same parent survey, and for the base station if it's your own.

Here is an example of how to post a raw data file of a rover in Python 3.x

import requests

host = 'http://api.rinexlab.com'
version = 'v1'

auth_token = 'ey...Ugs' # token retrieved from the login process

r = requests.post(f'{host}/{version}/ppk/surveys/<survey_id>/rovers/<rover_id>/file',
	files={
		"file": open('<file_name>', 'rb')
	},
headers={'Authorization': f'Bearer {auth_token}'}
)
rover = r.json()
print(rover)

Retrieve PPK surveys

GET http://api.rinexlab.com/v1/ppk/surveys

You can search a survey based on its name like this.

GET http://api.rinexlab.com/v1/ppk/surveys?search=<survey_name>

It's a matching search so you may input only the first characters of the survey name.

Here is a survey search example in Python 3.x.

import requests

host = 'http://api.rinexlab.com'
version = 'v1'

auth_token = 'ey...Ugs' # token retrieved from the login process

r = requests.get(f'{host}/{version}/ppk/surveys',
	params={
		"search": <survey_name>
	},
headers={'Authorization': f'Bearer {auth_token}'}
)

print(r.json())

Retrieve the details of a PPK survey

GET http://api.rinexlab.com/v1/ppk/surveys/<survey_id>

Retrieve the details of a rover

GET http://api.rinexlab.com/v1/ppk/surveys/<survey_id>/rovers/<rover_id>

Download the PPK results

GET http://api.rinexlab.com/v1/ppk/surveys/<survey_id>/rovers/<rover_id>/results

< Back to API menu