How can a Python program search the web with Tavily API?
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
- It needs a key and the internet. Without a valid key in
.env, or without a connection, the program stops with an error. - The free plan has limits. Tavily allows a fixed number of searches per month at no cost; heavy use needs a paid plan.
- The answer is only as good as the pages found. Tavily reads web pages and writes a summary, so an unclear question or poor sources give a poor answer. Asking a precise question helps.
Further reading
- The Tavily documentation lists everything the
searchcall can tune, such as how many pages to read. - https://www.tavily.com/ is where you sign up and copy your API key.
- How to mitigate AI hallucination with Retrieval-Augmented Generation (RAG) by providing a webpage? shows another way to give a model fresh facts: fetching a page yourself instead of asking a search service.