You are here:
< Back

The Python connector gives an easy entry-point to use OKAPI software from within your own python code. We recommend using the package provided via PyPI (see below), as this is updated with every release of OKAPI and actively maintained. If you prefer building your own code, you find the complete source code of the connector on Github. Note though that you have take care of the maintenance yourself.

This complete section is split into the following sections:

  1. Installing and updating the connector using PIP explains you, how to install the OKAPI package on your machine.
  2. Using the connector explains the general features of the connector as well as a short introduction into the error handling.
  3. Running the first calculation gives you a script including an exemplary log-in, sending and getting of the request.

We suggest that you go through the items once to ensure that you do not miss any important information.

Installing and updating the connector using PIP

Note: We recommend to always work in virtual environment with python to avoid cluttering your installation.

The connector has been designed to run with python3. Therefore, make sure that you are using python3 for all commands. Depending on your system configuration, phyton might point to python3 already, or not. So make sure you know what you are using.

To install the OKAPI connector, run (if you are using the powershell on Windows, replace python3 with python.exe):

python3 -m pip install okapi-python-connector

You now have successfully installed the latest version of the okapi-python-connector.

You always should make sure that the version of the python connector matches that of the OKAPI software. You can get the current version of the python connector using pkg_resources in python (again: change python3 into python.exe on Windows):

python3 -c "import pkg_resources; print(pkg_resources.get_distribution('okapi-python-connector').version)"

If you need to upgrade your python connector, run (use python.exe on windows):

python3 -m pip install okapi-python-connector --upgrade

Alternatively, you can get the complete source code of the connector on Github.

Using the connector

Generally, using the connector is very easy. After installing, you have to import the needed functions into your current code:

from okapi_pkg.okapi_init import okapi_init
from okapi_pkg.okapi_send_request import okapi_send_request
from okapi_pkg.okapi_get_result import okapi_get_result

Once this is done, the order how you use the API is always the same: In the beginning of your script (or every 24 hrs), you have to retrieve the JWT token from Auth0 using okapi_init():

okapi_login, error = okapi_init("OKAPI_URL", "YOUR_USERNAME","YOUR_PASSWORD")

The function returns a dict okapi_login, which mostly contains your JWT token, needed to get server access, and an error dict. The latter one contains three fields which give you an overview status as well as some further information. Make sure to _always_ check against the error['status']to catch your code in case something went wrong. It can contain the values FATAL, WARNING, INFO and NONE. In case of fatal errors, you should never use the result that might have been delivered. If you get a warning, you should check the reason for that. In most cases, it is nothing of concern. But especially if you get a warning together with an error[‘web_response’] of 202, it means that your process has been accepted, but is not fully processed yet. In that case, you should ask for the results short later again! Infos might be interesting to read, but do not indicate that something went wrong. If you get none, it means that no message was returned. error['message']gives you some extra information on the error that occurred, error['web_status']returns the http status code from the last request. Knowing this one is very helpful, in case there are issues with the internet connectivity, authentication or our server. Here is one example how to check the error:

if (error.get('status','') == 'FATAL'):

Once you have received your token, you are ready to send requests. To send a request, you have to prepare a json object containing the description of your request. In python, you can use dicts for that, which are formatted identically to json. A detailed description of the available endpoints and the datatypes you can send is given in the API-Documentation. If that is set up, you send a request as following:

request, error = okapi_send_request(okapi_login, request_body, 'endpoint_url')

You see that you have to provide the okapi_login, the request_body, which contains your request as dict, and the endpoint_url, which is given in the API-Documentation for all functionalities available. The function returns and error dict, which is of the same format as received after initialization, and a request. The latter one only contains an id which is used by the server to identify your results. You won’t have to do anything with it, but pass it to the function to receive the results. Again, make sure to catch at least FATAL errors.

Now the server is doing your calculations. Depending on the type of request, this might take a little bit. In python you can use time.sleep(seconds_to_sleep) from time to let your program wait a moment. Alternatively, you can also run a while loop until your request has been fully processed. The full http responses are given in the API documentation, but in short: If you get an error[‘web_response’] returns a 202, it means your request is still being processed. If you are getting a error[‘web_response’], you got a fully processed request (the latter one is described in the example below). Then, get your result:

result, error = okapi_get_result(okapi_login, request, 'endpoint_url')

Again, you have to provide the okapi_login, alongside with the request you got before and the endpoint_url. You find the description of these also in the API documentation. Note that we are currently introducing a „generic“ API, which allows more flexible data types, which will be the standard in the future. It is kept flexible here, as you can receive the results from many requests in different formats. So, here you basically define in which format you would like to retrieve your result. The function then returns your result as well as the already known error dict. From there, you can use the results for whatever purpose you are interested in.

Running the first calculation

For an easy start, you find a python script called on Github, noted above. Make sure that you import the routines correctly, if you use that. Furthermore, make sure that you entered your username and password in the call of the authentication routine. If you just need one first example, you can also use the following python script. It calculates the pass of a satellite over a groundstation.


import time

from okapi_pkg.okapi_init import okapi_init
from okapi_pkg.okapi_send_request import okapi_send_request
from okapi_pkg.okapi_get_result import okapi_get_result

# Init --> Get a token to run the analyses
# For auth info: See or contact us
okapi_login, error = okapi_init("", LOGIN,
# check for the error status
if (error.get('status','') == 'FATAL'):
    exit('Error during authentification.')

# Pass predictions

# # Prepare your request
pass_pred_request_body = {
    "tle": "1 25544U 98067A   18218.76369510  .00001449  00000-0  29472-4 0  9993\n2 25544  51.6423 126.6422 0005481  33.3092  62.9075 15.53806849126382",
    "simple_ground_location": {
        "longitude": 10.645,
        "latitude": 52.3283,
        "altitude": 0.048
    "time_window": {
        "start": "2018-08-07T18:00:00.000Z",
        "end": "2018-08-08T00:00:00.000Z"

# # send different pass prediction pass prediction requests
# # send a request to use SGP4 for pass prediction
request_sgp4, error = okapi_send_request(okapi_login, pass_pred_request_body,
if (error.get('status','') == 'FATAL'):

# loop until the result has been fully processed. Alternatively, you could
# also just "sleep" for a while
counter = 0
error.get('web_status','') = 202
while ((counter < 15) and (error.get('web_status','') == 202)):

  # get the result from SGP4
  result_sgp4, error = okapi_get_result(okapi_login, request_sgp4,
  if (error.get('status','') == 'FATAL'):
  elif(error.get('status','') == 'WARNING'):