CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-algoliasearch

A fully-featured and blazing-fast Python API client to interact with Algolia's search-as-a-service platform.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

analytics-insights.mddocs/

Analytics and Insights

Comprehensive analytics for search performance, user behavior tracking, and business insights including click-through rates, conversion metrics, and user interaction data. These services provide deep visibility into search usage patterns and help optimize the search experience.

Capabilities

Analytics Client

Analyze search performance and business metrics with comprehensive reporting capabilities.

class AnalyticsClient:
    def __init__(
        self,
        app_id: Optional[str] = None,
        api_key: Optional[str] = None,
        transporter: Optional[Transporter] = None,
        config: Optional[AnalyticsConfig] = None
    ) -> None: ...

    @classmethod
    def create_with_config(
        cls, 
        config: AnalyticsConfig, 
        transporter: Optional[Transporter] = None
    ) -> AnalyticsClient: ...

    async def close(self) -> None: ...
    async def set_client_api_key(self, api_key: str) -> None: ...

Conversion and Performance Metrics

Track and analyze key performance indicators for search effectiveness.

async def get_click_through_rate(
    self,
    index: str,
    start_date: str,
    end_date: str,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetClickThroughRateResponse:
    """
    Get click-through rate metrics for searches.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)  
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetClickThroughRateResponse with CTR metrics
    """

async def get_conversion_rate(
    self,
    index: str,
    start_date: str,
    end_date: str,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetConversionRateResponse:
    """
    Get conversion rate metrics for searches.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetConversionRateResponse with conversion metrics
    """

async def get_add_to_cart_rate(
    self,
    index: str,
    start_date: str,
    end_date: str,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetAddToCartRateResponse:
    """
    Get add-to-cart rate metrics for searches.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - tags: Filter by specific tags 
    - request_options: Additional request options
    
    Returns:
    GetAddToCartRateResponse with add-to-cart metrics
    """

async def get_purchase_rate(
    self,
    index: str,
    start_date: str,
    end_date: str,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None  
) -> GetPurchaseRateResponse:
    """
    Get purchase rate metrics for searches.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetPurchaseRateResponse with purchase metrics
    """

Search Volume and Usage Analytics

Analyze search patterns, query volume, and user engagement metrics.

async def get_search_volume(
    self,
    index: str,
    start_date: str,
    end_date: str,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetSearchVolumeResponse:
    """
    Get search volume metrics over time.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)  
    - end_date: End date (YYYY-MM-DD format)
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetSearchVolumeResponse with volume metrics
    """

async def get_searches_no_results(
    self,
    index: str, 
    start_date: str,
    end_date: str,
    limit: Optional[int] = None,
    offset: Optional[int] = None,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetSearchesNoResultsResponse:
    """
    Get searches that returned no results.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - limit: Maximum number of results to return
    - offset: Offset for pagination
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetSearchesNoResultsResponse with zero-result queries
    """

async def get_searches_no_clicks(
    self,
    index: str,
    start_date: str, 
    end_date: str,
    limit: Optional[int] = None,
    offset: Optional[int] = None,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetSearchesNoClicksResponse:
    """
    Get searches that received no clicks.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - limit: Maximum number of results to return
    - offset: Offset for pagination
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetSearchesNoClicksResponse with zero-click queries
    """

Top Searches and Popular Content

Identify trending searches and popular content to optimize user experience.

async def get_top_searches(
    self,
    index: str,
    start_date: str,
    end_date: str,
    limit: Optional[int] = None,
    offset: Optional[int] = None,
    tags: Optional[str] = None,
    order_by: Optional[str] = None,
    direction: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetTopSearchesResponse:
    """
    Get most popular search queries.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - limit: Maximum number of results to return
    - offset: Offset for pagination
    - tags: Filter by specific tags
    - order_by: Sort field (searchCount, clickThroughRate, etc.)
    - direction: Sort direction (asc, desc)
    - request_options: Additional request options
    
    Returns:
    GetTopSearchesResponse with popular queries
    """

async def get_top_hits(
    self,
    index: str,
    start_date: str,
    end_date: str,
    limit: Optional[int] = None,
    offset: Optional[int] = None,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetTopHitsResponse:
    """
    Get most clicked search results.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - limit: Maximum number of results to return
    - offset: Offset for pagination
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetTopHitsResponse with popular results
    """

async def get_top_filters(
    self,
    index: str,
    start_date: str,
    end_date: str,
    limit: Optional[int] = None,
    offset: Optional[int] = None,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetTopFiltersResponse:
    """
    Get most used search filters.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - limit: Maximum number of results to return
    - offset: Offset for pagination
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetTopFiltersResponse with popular filters
    """

Revenue and User Analytics

Track revenue attribution and user engagement metrics.

async def get_revenue(
    self,
    index: str,
    start_date: str,
    end_date: str,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetRevenueResponse:
    """
    Get revenue metrics attributed to search.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetRevenueResponse with revenue data
    """

async def get_users_count(
    self,
    index: str,
    start_date: str,
    end_date: str,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetUsersCountResponse:
    """
    Get unique user count metrics.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetUsersCountResponse with user metrics
    """

async def get_top_countries(
    self,
    index: str,
    start_date: str,
    end_date: str,
    limit: Optional[int] = None,
    offset: Optional[int] = None,
    tags: Optional[str] = None,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetTopCountriesResponse:
    """
    Get top countries by search usage.
    
    Parameters:
    - index: Index name to analyze
    - start_date: Start date (YYYY-MM-DD format)
    - end_date: End date (YYYY-MM-DD format)
    - limit: Maximum number of results to return
    - offset: Offset for pagination
    - tags: Filter by specific tags
    - request_options: Additional request options
    
    Returns:
    GetTopCountriesResponse with country metrics
    """

Insights Client

Track user behavior and interaction events for personalization and analytics.

class InsightsClient:
    def __init__(
        self,
        app_id: Optional[str] = None,
        api_key: Optional[str] = None,
        transporter: Optional[Transporter] = None,
        config: Optional[InsightsConfig] = None
    ) -> None: ...

    @classmethod
    def create_with_config(
        cls, 
        config: InsightsConfig, 
        transporter: Optional[Transporter] = None
    ) -> InsightsClient: ...

    async def close(self) -> None: ...
    async def set_client_api_key(self, api_key: str) -> None: ...

Event Tracking

Track user interactions for personalization and analytics.

async def push_events(
    self,
    insights_events: Union[InsightsEvents, dict],
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> EventsResponse:
    """
    Push user interaction events to Algolia.
    
    Parameters:
    - insights_events: Events data to track
    - request_options: Additional request options
    
    Returns:
    EventsResponse with processing confirmation
    """

async def click_through_events(
    self,
    click_through_events: Union[ClickThroughEvents, dict],
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> EventsResponse:
    """
    Track click-through events on search results.
    
    Parameters:
    - click_through_events: Click event data
    - request_options: Additional request options
    
    Returns:
    EventsResponse with processing confirmation
    """

async def conversion_events(
    self,
    conversion_events: Union[ConversionEvents, dict],
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> EventsResponse:
    """
    Track conversion events (purchases, signups, etc.).
    
    Parameters:
    - conversion_events: Conversion event data
    - request_options: Additional request options
    
    Returns:
    EventsResponse with processing confirmation
    """

async def purchase_events(
    self,
    purchase_events: Union[PurchaseEvents, dict],
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> EventsResponse:
    """
    Track purchase events with revenue data.
    
    Parameters:
    - purchase_events: Purchase event data
    - request_options: Additional request options
    
    Returns:
    EventsResponse with processing confirmation
    """

async def view_events(
    self,
    view_events: Union[ViewEvents, dict],
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> EventsResponse:
    """
    Track view events on content or products.
    
    Parameters:
    - view_events: View event data
    - request_options: Additional request options
    
    Returns:
    EventsResponse with processing confirmation
    """

User Profile Management

Manage user profiles and behavioral data.

async def get_user_profile(
    self,
    user_token: str,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> GetUserProfileResponse:
    """
    Get user profile and behavioral data.
    
    Parameters:
    - user_token: Unique user identifier
    - request_options: Additional request options
    
    Returns:
    GetUserProfileResponse with user data
    """

async def delete_user_profile(
    self,
    user_token: str,
    request_options: Optional[Union[dict, RequestOptions]] = None
) -> dict:
    """
    Delete a user profile and all associated data.
    
    Parameters:
    - user_token: Unique user identifier
    - request_options: Additional request options
    
    Returns:
    Deletion confirmation response
    """

Usage Examples

Track User Interactions

from algoliasearch.insights.client import InsightsClient

# Initialize client
client = InsightsClient("YOUR_APP_ID", "YOUR_API_KEY")

# Track click event
response = await client.click_through_events({
    "events": [{
        "eventType": "click",
        "eventName": "Product Clicked",
        "index": "products",
        "userToken": "user-123",
        "timestamp": int(time.time() * 1000),
        "objectIDs": ["product-456"],
        "positions": [1],
        "queryID": "query-789"
    }]
})

# Track conversion event
response = await client.conversion_events({
    "events": [{
        "eventType": "conversion", 
        "eventName": "Purchase",
        "index": "products",
        "userToken": "user-123",
        "timestamp": int(time.time() * 1000),
        "objectIDs": ["product-456"],
        "queryID": "query-789"
    }]
})

Analyze Search Performance

from algoliasearch.analytics.client import AnalyticsClient
from datetime import datetime, timedelta

# Initialize client
client = AnalyticsClient("YOUR_APP_ID", "YOUR_API_KEY")

# Get last 30 days of analytics
end_date = datetime.now().strftime("%Y-%m-%d")
start_date = (datetime.now() - timedelta(days=30)).strftime("%Y-%m-%d")

# Get click-through rate
ctr_response = await client.get_click_through_rate(
    index="products",
    start_date=start_date,
    end_date=end_date
)

print(f"Click-through rate: {ctr_response.rate}%")

# Get top searches
top_searches = await client.get_top_searches(
    index="products",
    start_date=start_date,
    end_date=end_date,
    limit=10
)

for search in top_searches.searches:
    print(f"Query: {search['search']} - Count: {search['count']}")

Types

# Analytics response types
class GetClickThroughRateResponse(BaseModel):
    rate: float
    click_count: int
    search_count: int
    dates: List[dict]

class GetConversionRateResponse(BaseModel):
    rate: float
    conversion_count: int
    click_count: int
    dates: List[dict]

class GetTopSearchesResponse(BaseModel):
    searches: List[dict]
    count: int

class GetRevenueResponse(BaseModel):
    revenue: dict
    dates: List[dict]

# Insights event types
class InsightsEvents(BaseModel):
    events: List[InsightsEvent]

class InsightsEvent(BaseModel):
    event_type: str
    event_name: str
    index: str
    user_token: str
    timestamp: Optional[int] = None
    object_ids: Optional[List[str]] = None
    positions: Optional[List[int]] = None
    query_id: Optional[str] = None

class EventsResponse(BaseModel):
    status: int
    message: str

class GetUserProfileResponse(BaseModel):
    user_token: str
    last_event_at: str
    clusters: Optional[dict] = None
    personalization: Optional[dict] = None

Install with Tessl CLI

npx tessl i tessl/pypi-algoliasearch

docs

ab-testing.md

analytics-insights.md

data-ingestion.md

index.md

monitoring-management.md

query-suggestions.md

recommendations.md

search-operations.md

tile.json