A Beginners Guide to APIs in Python - Finding Nearby Aircraft

APIs or Application Programming Interfaces are a super useful programming tool that interfaces two programmes data and information. APIs are used for almost everything you can think of, from tracking traffic to sending football scores and everything in between. They sound daunting but once you learn how they work they can be super easy to work with!

This guide aims to be a simple guide to explain the basics of interfacing with an API, grasping the basics of how they work and helping you to write an example a programme to automatically gather data about nearby aircraft using the OpenSkyNetwork API.

This example requires no logins and the API is free to use. You should also be able to apply this example to any API as long as you change the url, method and parameters to fit!

Supplies

Python 3
Internet Connection

Step 1: Installing Required Libraries

In the first step we will get all the modules we need to run our script.

We are going to require two libraries to make our script work. They are:

requests - this turns HTTP into simpler, more human readable lines of code in Python.
json - this allows us to import data in JavaScript object notation (json) into Python.

To install the requests library we run the command

pip install requests

We do not need to install the json library as this is included with all Python installs.

Step 2: Creating the Programme Environment

So first run the command to create a new python programme file:

sudo nano yourfilename.py

Once in the nano editor we want to use the modules mentioned in step 1 via the python import function.

import requests
import json

Step 3: Understanding the API Syntax

To use an API we have to call the URL it is hosted on then request the data. For this example we are using the OpenSkyNetwork API. This API is free to use personally and has data on all Aircraft using ADS-B (a type of aircraft radio broadcasting) across the world. The official documentation can be found here. We will be using the REST API.

Any API is made of multiple parts:

Base URL - The address that must be called to access the API.
Method (optional) - The method the data is requested and sent.
Parameters (optional) - Used for filtering the data that is held by the API.

From the link above we find the host url of the API we want to use is:

https://opensky-network.org/api

and it accepts the methods of:

  /states
  /flight
  /tracks

We are going to use the /states method as this can be used to request all flight data. The /states method also has two sub-methods. We only care about the /all sub-method for this example.

Lastly the /states/all methodaccepts the parameters of:

time - (integer) The time in seconds since epoch (Unix time stamp to retrieve states for.)
icao24 - (string) One or more ICAO24 transponder addresses represented by a hex string (e.g. abc9f3).
lamin - (float) lower bound for the latitude in decimal degrees
lomin - (float) lower bound for the longitude in decimal degrees
lamax - (float) upper bound for the latitude in decimal degrees
lomax - (float) upper bound for the longitude in decimal degrees

Therefore if we want to retrieve the data for the aircraft with icao24 value of 407930 we use the url:

https://opensky-network.org/api/states/all?icao24=407930

Entering this url on an internet browser, like Mozilla, you should get a result similiar to the picture above. (You may need to find the icao24 of an aircraft in flight. This can easily be found at https://globe.adsbexchange.com/ and copying the hex value of an aircraft and replacing the 407930 at the end of the url with this value).

Step 4: Getting API Into Python

So now we have understood how to request from the API we can use this in our python script.

Firstly we are going to set the following values from what we found in the API documentation:

api_url = 'https://opensky-network.org/api'
api_method = '/states/all'

As we have also seen we can request the data from aircraft based on their location from the /states parameters.

Therefore lets set some values for these parameters. I have arbitarily set my location co-ordinates as the Eiffel Tower with a ±0.2° box around it. You can set these to anything you like however.

my_latitude = 48.8584
my_longitude = 2.2945
lamax = str(my_latitude + 0.2)
lamin = str(my_latitude - 0.2)
lomax = str(my_longitude + 0.2)
lomin = str(my_longitude - 0.2)

The values have been set to strings as any url has to be a string.

Lets now combine this into a url that the API can use:

combined_url = api_url + api_method + '?lamax=' + lamax + '&lamin=' + lamin + '&lomax=' + lomax + '&lomin=' + lomin

Note how a ? is required before specifying the parameters and an & is required to seperate each parameter. This is true of almost all API urls.

Step 5: Getting the Data Into Our Script

Now we have our URL we have to request and format the data from it. This is where our requests and json modules come in.

We want to use request.gets to get the data from the url so this looks like:

api_data = requests.get(combined_url)

I have set the variable api_data to hold the response from the requests.get function.

Now to convert this data to a python dictionary we use the function json.loads like so:

api_data_py = json.loads(api_data.text)

The .text must be included to turn the json data to text for our python dictionary.

Step 6: Finishing the Script

Now we have the data in a dictionary we can use it however we like. In this example I have created the variable states that stores all the values listed under 'states' recieved from the API. I have then made the script print the data from the first aircraft stored in the states variable.

So you should end up with a script like this:

import requests
import json

api_url = 'https://opensky-network.org/api'
api_method = '/states/all'

my_latitude = 48.8584
my_longitude = 2.2945
lamax = str(my_latitude + 0.2)
lamin = str(my_latitude - 0.2)
lomax = str(my_longitude + 0.2)
lomin = str(my_longitude - 0.2)

combined_url = api_url + api_method + '?lamax=' + lamax + '&lamin=' + lamin + '&lomax=' + lomax + '&lomin=' + lomin

api_data = requests.get(combined_url)
api_data_py = json.loads(api_data.text)

states = api_data_py['states']

print(states[0])