How to Use API Query Parameters with Python Requests: A Step‑by‑Step Guide

Using API with Query Parameters

In the previous example we called http://api.open-notify.org/astros.json without any parameters, simply issuing a GET request that returned the current number of people in space.

Many API endpoints require additional query parameters. For instance, http://api.open-notify.org/iss-pass.json returns the International Space Station's upcoming passes for a given latitude and longitude.

Sending Request with Parameters

The API documentation specifies two parameters: lat (latitude) and lon (longitude). In requests you pass them via the params argument, which accepts a Python dictionary.

parameters = {
    "lat": 40.71,
    "lon": -74
}

You can also embed the parameters directly in the URL, e.g. http://api.open-notify.org/iss-pass.json?lat=40.71&lon=-74, but using a dictionary lets requests handle proper encoding.

Send the request and print the JSON response:

response = requests.get("http://api.open-notify.org/iss-pass.json", params=parameters)
print(response.json())

A typical response looks like this:

{
    "message": "success",
    "request": {
        "altitude": 100,
        "datetime": 1568062811,
        "latitude": 40.71,
        "longitude": -74.0,
        "passes": 5
    },
    "response": [
        {"duration": 395, "risetime": 1568082479},
        {"duration": 640, "risetime": 1568088118},
        {"duration": 614, "risetime": 1568093944},
        {"duration": 555, "risetime": 1568099831},
        {"duration": 595, "risetime": 1568105674}
    ]
}

Parsing JSON Response

The response key contains a list of pass times. Extract it and optionally pretty‑print:

pass_times = response.json()['response']
jprint(pass_times)

Collect the risetime values:

risetimes = []
for d in pass_times:
    risetimes.append(d['risetime'])
print(risetime)

Output:

[1568082479, 1568088118, 1568093944, 1568099831, 1568105674]

Converting Timestamps

These numbers are Unix timestamps (seconds since 1970‑01‑01). Convert them to human‑readable dates with datetime.fromtimestamp():

from datetime import datetime

times = []
for rt in risetimes:
    time = datetime.fromtimestamp(rt)
    times.append(time)
    print(time)

Result:

2020-12-09 21:27:59
2020-12-09 23:01:58
2020-12-10 00:39:04
2020-12-10 02:17:11
2020-12-10 03:54:34

This shows that the ISS passes over New York City five times within roughly seven hours.

Key Takeaways

Understanding what an API is.

How to make HTTP requests and read responses in Python.

How to include query parameters using a dictionary.

How to extract and display JSON data.

How to convert Unix timestamps to readable dates.