UnacatLib Documentation

Welcome to UnacatLib’s documentation! This is the Python client library for interacting with the Unacast API.

Quick Start

Installation

You can install UnacatLib using pip:

pip install unacatlib

Usage Example

Here’s a complete example showing how to query foot traffic data for specific brands:

from unacatlib.query_client import QueryClient, FilterClause
import os

# Initialize the client using environment variable
client = QueryClient()  # Will use UNACAST_API_KEY environment variable
# Or provide the API key directly:
# client = QueryClient(api_key="your-api-key")

# First, let's see what data references are available
data_refs = client.list_data_references()
print("Available data references:")
print(data_refs.data_references.to_df())

# Query foot traffic data for all Target stores
response = client.list_records(
    data_reference_name="ml_visitation.foot_traffic_month",
    filters=[
        FilterClause(
            field_name="brands",
            operator="==",
            value="Target"
        )
    ],
    limit=500  # Optional: limit the number of records
)

# Convert to pandas DataFrame for easy analysis
df = response.records.to_df()
print("\nFoot traffic data:")
print(df.head())

# You can also search for available values in a field
brands = client.search_field_values(
    data_reference_name="ml_visitation.foot_traffic_month",
    field="brands",
    term="Walm"  # Search for brands containing "Wal"
)
print("\nAvailable brands containing 'Walm':")
print(brands.values)

Table of Contents

Contents:

API Reference

For detailed API documentation, see the Query Client section.

Indices and tables