Skip to content

Powershell (Windows 10)

If you are using Windows as your operating system, you should have access to the powershell. Note that your admin has to grant you the right to execute powershell scripts before you can do that (look for the Set-ExecutionPolicy cmdlet)! Before getting started, one last recommendation: While it is possible to run the commands inline, we recommend you to paste them one-by-one in a shell script! This will facilitate all future requests and furthermore make the debugging much easier. Furthermore, some of the operations are time critical to a certain degree. When embedded in a script, you do not have to worry about that. If you prefer reading to writing yourself, the code that is to be created in this tutorial can also be found here.

Authentication

To be able to use OKAPI, you have to authenticate. We use services from Auth0 for that. Therefore, before being able to send any requests to our server, you have to get a token from Auth0. This token is received by sending a HTTP POST request to Auth0. As every HTTP request, it contains a header and a body. When using wget, it is most easy to send the body as a file (note: in powershell, wget is an alias for the Invoke-WebRequest cmdlet). Depending on the programming language you will work with in the future, you can use build-in data types for that (for example structs in Matlab, or dicts and lists in Python).

The body file to send an authentication request to Auth0 looks as follows: 

{
    "grant_type":"password",
    "username": "your-username",
    "password": "your-password",
    "audience": "https://api.okapiorbits.space/picard",
    "client_id": "jrk0ZTrTuApxUstXcXdu9r71IX5IeKD3",
    "scope": "scopes-are-ignored-for-now"
}
Create a file like this using an editor of your choice and save it (for example under the name authentication_request.json). Insert your password and email address. For the scope you can currently put any string, but make sure that you do not omit that field. Now, you are ready to send the request to the server:

wget -Uri https://okapi-development.eu.auth0.com/oauth/token -Headers @{"content-type"="application/json"} -Method POST -Body $(get-content authentication_request.json -raw) -OutFile "token.json"

You see that the request is split into the body (make sure to use your filename) and the header. In the header you only need to define the content-type. Furthermore, you tell wget where to save the output. As we want to use the token afterwards, it makes sense to save it to a file (for example token.json). Now execute the command. If it runs without any further output, it is a good sign. The token that is returned should look like the following:

{
    "access_token": "very_long_string_with_token",
    "scope": "string_with_your_scopes",
    "expires_in": 86400,
    "token_type": "Bearer"
}

Important in here are the scope and expires_in fields: In the first, all the endpoints you have access to are defined. When using the Demo account, you have full access to all available endpoints for a duration of 30 days. After that, the endpoints depend on your plan. The second field tells you how long the token is valid in seconds. Current standard is 86400 seconds ( = 1 day). After that, you would have to get the token again. If you are using OKAPI frequently, you could just create a recurring job (for example using cronjob), which refreshes your token automatically once per day.

Sending a request

Now you have finished the authentication, so you are ready to send your first request. Using wget, the command to do that is the following: 

$token = (Get-Content '.\token.json' | ConvertFrom-Json).access_token
wget -Uri https://api.okapiorbits.com/predict-passes/sgp4/requests -Headers @{"content-type"="application/json";"Accept"="application/json";"Authorization"="Bearer "+$token} -Method POST -Body $(get-content pass_prediction_request.json -raw) -OutFile "request_response.json"
Start-Sleep -s 2
The first line is a „short-cut“ to get the token from the token.json file. You read the value of the access token from that file and send it to the token variable. The second line is the actual request. It is very similar to the command to retrieve the access token: Again, you define a body (given as a file, we come to that just after) and the header. This time, the header needs to now the content-type and the accept value. Furthermore, you include the access token, which is why we copied it into the variable (if you are unable to use jq, you have to copy the value of the access token into the request). This time, instead of using the GET method we use POST. The request is sent directly to OKAPI, using the endpoint for pass prediction requests. Also as before, the response from the server is written to an output file, which we call request_response.json. The Start-Sleep is included in the command to give the server a moment to process the request before you continue (which is important during the next step). Now, the last thing that is needed is to provide input on the pass prediction you actually want to perform. In the command stated above, the request is defined in the file pass_prediction_request.json and looks as follows:

{
    "orbit": {
        "type": "tle.txt",
        "content": "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"
    },
    "ground_location": {
        "type": "ground_loc.json",
        "content" :{
            "longitude":10.645,
            "latitude":52.3283,
            "altitude":0.048
        }
    },
    "time_window":{
        "type": "tw.json",
        "content": {
            "start":"2018-08-06T18:19:44.256Z",
            "end":"2018-08-07T00:00:00.000Z"
        }
    }
}

Note that the two lines of the TLE are merged into one and the line break is expressed as \n. You have to keep the format exactly as described above. The location of the ground station is given in WGS-84 coordinates. Longitude and latitude are given in degree, the altitude in km. The service will return all passes of the satellite during the defined time window. Submit a TLE string that is close to the time window defined (maximum a couple of days old). The older the TLE, the less accurate the results that are returned.

Now, execute the command. It should send the message, and the server returns a HTTP/1.1 202 Accepted, if everything went well. If you get a http code 401, something was wrong with your authentication. If you get a timeout, you either misspelled the server’s address, or our server is down. If you get a 500, most probable your request contained some wrong format. In that case (and in all other cases), check out the response. A good response looks like this:

{
    "request_id": "87e3a5ab-e1f0-4387-8416-c90a8f2675b0",
    "status": {
        "type": "REMARK",
        "text": "Service request has been submitted successfully"
    }
}

Most important is the request_id. Use this value to retrieve the result from your computation. In the state message, you will get some further information if the request was not accepted.

Receiving the result

You have now sent the first request, now it is time to collect the response. Your request needs a certain time for processing. For the pass prediction, it is generally less than a second, but give the server some time. If you asked for a response too soon, the server will return a 202 instead of 200, which means that the results are being processed now. The results you receive are incomplete. You can use sleep 2 for the bash to wait for 2 seconds.

The command to retrieve the results is:

$request_id = (Get-Content '.\request_response.json' | ConvertFrom-Json).request_id
wget -Uri https://api.okapiorbits.com/predict-passes/sgp4/results/${request_id}/summary -Headers @{"Authorization"="Bearer "+$token} -OutFile "pass_prediction_result.json"

The first line is again a shortcut to read the request_id from the server response of the request and strip the quotes from the request_id. If you have no access to jq, you can also just copy the number from that file. Same is valid for the access token, which is assumed to be contained in the same variable as for the request sent before. You can directly execute this command. You should receive a HTTP/1.1 200 OK from the server. This means, all went well. Possible other responses are:

  • 202: It indicates that the results are being processed now and the received content is not the complete yet.
  • 404: In this case either no pass was calculated because the satellite is not seen from the groundstation during the time window (this will be changed soon), or your request has not been processed yet.
  • 422: Unprocessible entity. Here, something was wrong with your request, which could not be detected by the API directly. Most probable, there is a defect in the TLE string. Check our the response, there should be more information available in the state message.

If everything went fine, look at your pass_prediction_result.json file. It contains a summary of all passes of the object during the specified time interval. For a more readable version of the result, use Get-Content .\pass_prediction_result.json | ConvertFrom-Json | ConvertTo-Json in your terminal.