> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Visualize theme volume evolution
## Overview
This guide demonstrates how to use the Bigdata Search Volume API endpoint (`/v1/search/volume`) to retrieve and visualize theme volume data over time. The script displays the evolution of documents, chunks, and sentiment for any given theme, helping you track narrative trends and coverage patterns.
Access the complete source code, requirements, and setup instructions.
## Features
✅ Retrieves theme volume data from the Bigdata Search Volume API
✅ Visualizes three key metrics: number of documents, number of chunks, and sentiment
✅ Displays daily values as bars (documents and chunks) or lines (sentiment)
✅ Overlays weekly average trends for better pattern recognition
✅ Generates high-resolution PNG charts with theme-specific filenames
✅ Supports custom date ranges and themes via command-line arguments
## Use Cases
The Search Volume endpoint is valuable for several scenarios:
* **Evaluate Coverage**: See how many unique documents Bigdata has available for your particular query
* **Narrative/Thematic Screeners**: Create a query and see how the defined narrative evolves over time
* **Query Strategy**: Check coverage and plan how to structure your queries accordingly
**Efficient Usage**: The `/v1/search/volume` endpoint consumes exactly 1 API Query Unit regardless of the time period queried (up to 60 weeks maximum), making it a very efficient way to visualize narrative evolution over time.
**Flexible Filtering**: The Search Volume endpoint supports all the same filters as the Search endpoint, including entity, source, category, keyword, and sentiment filters. For more details, check out the [Search Volume API specification](https://docs.bigdata.com/api-reference/search/search-volume).
## Prerequisites
* Python 3.9 or higher
* A Bigdata.com API key
### System Dependencies
Matplotlib requires some system libraries for chart generation.
```bash theme={null}
sudo apt-get install python3-tk
```
```bash theme={null}
# Usually pre-installed, but if needed:
brew install python-tk
```
Matplotlib should work out of the box with the pip installation.
## Setup
```bash theme={null}
git clone https://github.com/Bigdata-com/bigdata-docs-resources.git
cd bigdata-docs-resources/how_to_guides/api_theme_volume
```
```bash theme={null}
python -m venv venv
```
Activate the virtual environment:
```bash theme={null}
source venv/bin/activate
```
```bash theme={null}
venv\Scripts\activate
```
```bash theme={null}
pip install -r requirements.txt
```
Copy the `.env_template` file to `.env`:
```bash theme={null}
cp .env_template .env
```
Open the `.env` file and replace the placeholder value with your actual API key:
```
BIGDATA_API_KEY=your_bigdata_api_key_here
```
You can obtain your API key from the [Bigdata Platform](https://platform.bigdata.com/api-keys).
Never commit your `.env` file to version control. Add it to your `.gitignore` file.
## Usage
### Run the script
Run the script with required date range parameters:
```bash theme={null}
python theme_volume_evolution.py --start-date 2025-01-01 --end-date 2025-12-15
```
### Command-Line Arguments
| Argument | Short | Description | Required |
| -------------- | ----- | ----------------------------------------------------------- | -------- |
| `--start-date` | `-s` | Start date in format `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ` | Yes |
| `--end-date` | `-e` | End date in format `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ` | Yes |
| `--theme` | `-t` | Theme to search for (default: "Tariffs impact") | No |
### Examples
Basic usage with default theme:
```bash theme={null}
python theme_volume_evolution.py --start-date 2025-01-01 --end-date 2025-12-15
```
Using short flags:
```bash theme={null}
python theme_volume_evolution.py -s 2025-01-01 -e 2025-12-15
```
With a custom theme:
```bash theme={null}
python theme_volume_evolution.py -s 2025-01-01 -e 2025-12-15 --theme "Quantum computing chip"
```
View help:
```bash theme={null}
python theme_volume_evolution.py --help
```
## Output
The script generates a high-resolution (300 DPI) PNG chart with a timestamped filename:
```
{theme}_volume_evolution_YYYYMMDD_HHMMSS.png
```
The chart includes three subplots:
1. **Unique Documents per Day**: Daily document counts as bars with weekly average line
2. **Chunks per Day**: Daily chunk counts as bars with weekly average line
3. **Sentiment per Day**: Daily sentiment values as a line with weekly average line
## Example Charts
Here are example charts generated for different themes:
Theme: `"Tariffs impact"`
Theme: `"Quantum computing chip"`
Theme: `"Solid state batteries"`
Theme: `"Greenland"`
Theme: `"Venezuela"`
