English 繁體中文 简体中文

How can a Python program search the web with Tavily API?

Howard Pong Yuen Lam · AI Notes · November 3, 2026 · 4 min read

Programs sometimes need fresh facts from the internet: today's news, a price, an address. An ordinary search engine is built for humans — it returns pages of links mixed with ads, and a program cannot easily use that. Tavily is a search service built for programs instead: you send it a question in plain English, and it sends back a short, ready-made answer along with the web pages it used.

The program in this note asks Tavily the question “Where is Hong Kong?” and prints the answer, in 11 lines.

Getting a key first

Tavily needs to know who is asking, so the program presents an API key: a secret string of characters that works like a password. API stands for Application Programming Interface, the way one program talks to another over the internet. To get a key, sign up at https://www.tavily.com/; the free plan is enough for trying things out, and the key is shown on the dashboard.

The key must not be written inside the program itself, where anyone reading the code could take it. Instead it lives in a small file named .env in the same folder, containing one line:

TAVILY_API_KEY=paste-your-key-here

Create this file yourself after downloading the demo; it is not included in the zip, because a key is personal.

The program, piece by piece

import os

from dotenv import load_dotenv
from tavily import TavilyClient

load_dotenv()

Three libraries are brought in. os stands for operating system; here it is used to read environment variables, settings stored outside the code. load_dotenv reads the .env file and copies each line into those environment variables. TavilyClient is the Tavily library's connector, the object that sends questions to the service.

tavily_client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))

This creates the connector. os.getenv("TAVILY_API_KEY") reads the key that load_dotenv() just loaded from .env, and hands it to TavilyClient. From now on, every request the connector sends carries the key, so Tavily knows whose account has the request.

response = tavily_client.search("Where is Hong Kong?", include_answer=True)

The search call sends the question. include_answer=True asks Tavily not only for a list of web pages but also for a short answer written from those pages. The result comes back as a dictionary: a collection of named pieces, such as "answer" for the written answer and "results" for the list of pages.

print(response["answer"])

This picks the "answer" piece out of the dictionary and prints it. Change the question in the line above to ask something else.

The whole program

import os

from dotenv import load_dotenv
from tavily import TavilyClient

load_dotenv()

tavily_client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))
response = tavily_client.search("Where is Hong Kong?", include_answer=True)

print(response["answer"])

Running it on your own computer

Download the zip file and unzip it to a folder. The zip holds the program and a pyproject.toml project file. Add your own .env file with the key, as shown above. Then open the folder in Visual Studio Code and type these three lines in the terminal, one at a time:

uv python pin 3.12.10
uv sync
uv run tavily_search.py

The first line records which Python version this folder uses. The second line sets up the project and installs the two packages the program needs, tavily-python and python-dotenv. The third line runs the program. A few seconds later, the answer appears:

Hong Kong is located on the southeastern coast of China, at the eastern side of the Pearl River Delta, where the Pearl River meets the South China Sea. It sits directly south of Shenzhen and Guangdong province, making it a gateway between mainland China and the rest of the world.

The wording will probably differ when you run it, because Tavily writes a fresh answer from whatever pages it finds at that moment.

If you have not set up uv yet, start with How to install Visual Studio Code? and then the uv note for Windows or Mac.

Limitations

Further reading