In this lesson, you will learn how to make requests to a web server and handle responses in a program using Python code. To practice this, we will use an API called OpenWeatherMap which provides weather data (eg. current temperature and conditions) that developers can use in their apps or websites.

API stands for Application Programming Interface. An API is an interface that defines the interactions that can occur between different software applications such as the kinds of calls or requests that can be made, how to make requests/calls, the data formats that responses should be represented with, and the rules or conventions to follow. There are many different web APIs that allow you to use services or fetch different types of data that can be used within your own application (eg. fetch weather data to use in your own weather app).

A web API works by:

• making a request and specifying parameters in the request (your application sends the request to the API and specified parameters in the request eg. the current temperature in degrees Celcius for the location Sydney, Australia)

• getting a response (retrieving the requested data in a particular format eg. represented in JSON format)

• extracting the information to be used from the response

Example - fetch weather data

The OpenWeatherMap API allows us to fetch weather data for a location in a request and use that data in our own web apps. We will use the API to get the temperature and humidity for a particular city but there is much more data you can get from this API. To get started, we will just display weather data for one city in the terminal to test that our application can make requests and receive responses. Later on, you could build an app with a graphical user interface (GUI) where the user can enter the name of a city/suburb and the weather data could be displayed using icons and text in a GUI window.

Get your API key

To get started, go to https://openweathermap.org/api . Scroll down and click "Subscribe" under the heading “Current Weather Data”. Scroll down on the next page and click on “Get API key” in the “Free” plan column. You will need to sign up for a free account to get your API key. Alternatively, if you are already signed in, click on your account name in the top right corner of the screen and then click on My API keys to generate a new key. You will need to use this key in your app's code later.

Install the requests module

The requests module allows you to send HTTP requests and handle responses using Python. You’ll need to install the requests module as it is not installed by default. In your terminal, run the following command:

sudo pip3 install requests

After you have installed the requests module, you’ll be able to use its functions in your code by using the import requests statement in your application’s code.

Make a request

When making a request to an API, you will need to specify the URL (link) to the API request. This usually includes some parameters, such as the data you are requesting, the format the response should be in, and your API key.

In the example code below, copy and paste your OpenWeatherMap API key into the api_key variable to replace the existing value. You can modify the city and country code as well, and specify any other desired parameters in the URL (refer to the documentation on the OpenWeatherMap website).

Handling the response

In the code below, an if statement is used to check if the request was successful. A HTTP code of 200 (which means OK) will be received if the request was successful. If the request is successful, the program will then get the response data (which is in JSON format) and convert it into a Python dictionary. We can then reference specific key-value pairs in the dictionary just like we would with any other dictionary. There are some examples for getting the temperature, humidity, and description of the current conditions in the code below, but you can also refer to the OpenWeatherMap documentation to find out how to extract other data from the response.

Use the example code below to try this out - all you need to do is specify your OpenWeatherMap API key in the api_key variable. Run the code to test the program and if all goes well, you should have some weather data displayed in the terminal.