Build a Wikipedia Rabbit Hole Explorer in Python: Absolute Beginners Tutorial

You type "black holes" into Wikipedia, click a link to "general relativity," then to "Albert Einstein," then to "Zurich" — and suddenly it is 40 minutes later. This tutorial teaches you to recreate that experience in Python, building a program that automatically follows Wikipedia articles one link at a time using the public Wikipedia REST API.

By the end of this tutorial you will have a working Python script that starts on any Wikipedia topic you choose, prints the article title and a short summary, picks the first linked article, and repeats that process for as many hops as you set. Along the way you will learn how functions work, how loops repeat code, how Python reads data from the internet, and what JSON actually is — all in the context of a project you can run right now.

What You Will Build

The finished program is roughly 30 lines of Python. When you run it you will see output that looks like this:

Hop 1: Black hole
A black hole is a region of spacetime where gravity is so strong
that nothing — not even light — can escape...

Hop 2: General relativity
General relativity is Einstein's geometric theory of gravitation...

Hop 3: Albert Einstein
Albert Einstein was a German-born theoretical physicist who developed
the theory of relativity...

Hop 4: Zürich
Zürich is the largest city in Switzerland and the capital of the
canton of Zürich...

Each hop is one call to the Wikipedia API. The program reads the response, prints the summary, then extracts the title of the first linked article to use as the next starting point. That is the entire loop — simple on the surface, but it touches several real programming concepts all at once.

What Python Needs: The requests Library and JSON

Python can do a lot out of the box, but fetching data from the internet is not in its standard library. For that you install requests, a library that has become the standard choice for HTTP in Python because it keeps the code readable. Open a terminal and run the install command:

pip install requests

Once installed, you bring it into your script with an import statement at the top. You also import time — a standard library module — so you can add a small pause between requests and avoid hitting Wikipedia's servers too rapidly.

import requests
import time

An import statement tells Python to load a library so you can use its functions. Everything inside requests is now available to your script through the requests name.

Reading the Wikipedia API response

The Wikipedia REST API returns data in JSON format. Here is a simplified version of what the API sends back when you ask for the "Black hole" article:

{
  "title": "Black hole",
  "extract": "A black hole is a region of spacetime...",
  "content_urls": {
    "desktop": {
      "page": "https://en.wikipedia.org/wiki/Black_hole"
    }
  }
}

After calling response.json(), Python turns that text into a dictionary. You access the title with data["title"] and the summary with data["extract"], exactly the same way you would access any Python dictionary key.

Writing Your First Fetch Function

Rather than repeating the same request code over and over, you wrap it in a function. A function is a named block of code that you can call by name whenever you need it. Here is the fetch function for this project:

def fetch_article(title):
    url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{title}"
    headers = {"User-Agent": "RabbitHoleExplorer/1.0 (python-tutorial)"}
    response = requests.get(url, headers=headers)
    if response.status_code != 200:
        return None
    return response.json()

Let's walk through each line. def fetch_article(title): defines the function. The word in the parentheses, title, is a parameter — it is a placeholder for whatever article name you pass in when you call the function. The f-string on the second line builds the URL dynamically by inserting that title into the Wikipedia API address.

The headers dictionary sets a User-Agent string, which is a short description of your program. The Wikimedia Foundation asks that all API users include one so they can understand traffic patterns. Skipping it still works, but it is polite practice. requests.get() sends the HTTP request and stores the server's reply in the variable response.

The if block checks the HTTP status code. A status code of 200 means "everything is fine." Any other number means something went wrong — the article was not found, the server is busy, or the network failed. Returning None in that case gives the calling code a clear signal to stop or skip. If the status is 200, the function returns response.json(), which converts the raw text response into a Python dictionary.

Here is the complete program, combining all the pieces above:

import requests
import time

# ── Configuration ──────────────────────────────────────────
START_TOPIC = "Black_hole"   # use underscores for spaces
HOP_COUNT   = 5              # how many articles to follow
SUMMARY_LEN = 200            # characters to print per summary
# ───────────────────────────────────────────────────────────


def fetch_article(title):
    """Fetch a Wikipedia article summary by title.
    Returns a dict on success, or None on failure."""
    url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{title}"
    headers = {"User-Agent": "RabbitHoleExplorer/1.0 (python-tutorial)"}
    try:
        response = requests.get(url, headers=headers, timeout=10)
    except requests.exceptions.RequestException:
        return None
    if response.status_code != 200:
        return None
    return response.json()


def run_rabbit_hole(start, hops):
    current = start
    for hop in range(1, hops + 1):
        data = fetch_article(current)

        if data is None:
            print(f"Could not fetch '{current}'. Stopping.")
            break

        title   = data.get("title", current)
        extract = data.get("extract", "No summary available.")
        links   = data.get("linked_pages", [])

        print(f"\nHop {hop}: {title}")
        print(extract[:SUMMARY_LEN] + ("..." if len(extract) > SUMMARY_LEN else ""))

        if not links:
            print("No linked pages found. Stopping.")
            break

        # The next article is the first item in linked_pages
        current = links[0].get("title", "").replace(" ", "_")
        if not current:
            print("Could not determine next article. Stopping.")
            break

        time.sleep(1)   # be polite to the Wikipedia API


if __name__ == "__main__":
    run_rabbit_hole(START_TOPIC, HOP_COUNT)

"Simple is better than complex." — The Zen of Python, Tim Peters (PEP 20)

Python Learning Summary Points

1. A function defined with def lets you name a block of code and reuse it without rewriting it. Parameters like title make functions flexible — the same function can fetch any Wikipedia article by receiving a different title each time it is called.
2. The requests.get(url) call sends an HTTP GET request — the same kind your browser sends when you visit a page. The response object has a status_code attribute and a json() method that converts the response body into a Python dictionary.
3. A for loop combined with range(1, hops + 1) runs the loop body exactly hops times, with the variable hop incrementing on each pass. You use break to exit the loop early if an error occurs.
4. Dictionary .get(key, default) is safer than direct key access because it returns the default value instead of raising a KeyError when the key is missing — critical for API data where any field might be absent.
5. The if __name__ == "__main__": block at the bottom ensures the program only runs when you execute the file directly, not when another script imports it. It is a best practice even for short scripts.

From here, there are many directions to take the project. You could write the visited titles to a text file to save the trail, add a limit on how many characters to print so long articles do not flood the terminal, build a loop that asks the user to confirm each hop, or swap Wikipedia for a different public API entirely. The core skills — functions, HTTP requests, JSON parsing, and loops — transfer directly to any of those extensions.