.. unacatlib documentation master file, created by
   sphinx-quickstart on Wed Dec 11 14:51:21 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

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:

.. code-block:: bash

   pip install unacatlib

Usage Example
~~~~~~~~~~~

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

.. code-block:: python

   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
---------------

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   api/query_client

API Reference
------------

For detailed API documentation, see the :doc:`api/query_client` section.

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`