0
# Analytics and Insights
1

2
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.
3

4
## Capabilities
5

6
### Analytics Client
7

8
Analyze search performance and business metrics with comprehensive reporting capabilities.
9

10
```python { .api }
11
class AnalyticsClient:
12
    def __init__(
13
        self,
14
        app_id: Optional[str] = None,
15
        api_key: Optional[str] = None,
16
        transporter: Optional[Transporter] = None,
17
        config: Optional[AnalyticsConfig] = None
18
    ) -> None: ...
19

20
    @classmethod
21
    def create_with_config(
22
        cls, 
23
        config: AnalyticsConfig, 
24
        transporter: Optional[Transporter] = None
25
    ) -> AnalyticsClient: ...
26

27
    async def close(self) -> None: ...
28
    async def set_client_api_key(self, api_key: str) -> None: ...
29
```
30

31
### Conversion and Performance Metrics
32

33
Track and analyze key performance indicators for search effectiveness.
34

35
```python { .api }
36
async def get_click_through_rate(
37
    self,
38
    index: str,
39
    start_date: str,
40
    end_date: str,
41
    tags: Optional[str] = None,
42
    request_options: Optional[Union[dict, RequestOptions]] = None
43
) -> GetClickThroughRateResponse:
44
    """
45
    Get click-through rate metrics for searches.
46
    
47
    Parameters:
48
    - index: Index name to analyze
49
    - start_date: Start date (YYYY-MM-DD format)
50
    - end_date: End date (YYYY-MM-DD format)  
51
    - tags: Filter by specific tags
52
    - request_options: Additional request options
53
    
54
    Returns:
55
    GetClickThroughRateResponse with CTR metrics
56
    """
57

58
async def get_conversion_rate(
59
    self,
60
    index: str,
61
    start_date: str,
62
    end_date: str,
63
    tags: Optional[str] = None,
64
    request_options: Optional[Union[dict, RequestOptions]] = None
65
) -> GetConversionRateResponse:
66
    """
67
    Get conversion rate metrics for searches.
68
    
69
    Parameters:
70
    - index: Index name to analyze
71
    - start_date: Start date (YYYY-MM-DD format)
72
    - end_date: End date (YYYY-MM-DD format)
73
    - tags: Filter by specific tags
74
    - request_options: Additional request options
75
    
76
    Returns:
77
    GetConversionRateResponse with conversion metrics
78
    """
79

80
async def get_add_to_cart_rate(
81
    self,
82
    index: str,
83
    start_date: str,
84
    end_date: str,
85
    tags: Optional[str] = None,
86
    request_options: Optional[Union[dict, RequestOptions]] = None
87
) -> GetAddToCartRateResponse:
88
    """
89
    Get add-to-cart rate metrics for searches.
90
    
91
    Parameters:
92
    - index: Index name to analyze
93
    - start_date: Start date (YYYY-MM-DD format)
94
    - end_date: End date (YYYY-MM-DD format)
95
    - tags: Filter by specific tags 
96
    - request_options: Additional request options
97
    
98
    Returns:
99
    GetAddToCartRateResponse with add-to-cart metrics
100
    """
101

102
async def get_purchase_rate(
103
    self,
104
    index: str,
105
    start_date: str,
106
    end_date: str,
107
    tags: Optional[str] = None,
108
    request_options: Optional[Union[dict, RequestOptions]] = None  
109
) -> GetPurchaseRateResponse:
110
    """
111
    Get purchase rate metrics for searches.
112
    
113
    Parameters:
114
    - index: Index name to analyze
115
    - start_date: Start date (YYYY-MM-DD format)
116
    - end_date: End date (YYYY-MM-DD format)
117
    - tags: Filter by specific tags
118
    - request_options: Additional request options
119
    
120
    Returns:
121
    GetPurchaseRateResponse with purchase metrics
122
    """
123
```
124

125
### Search Volume and Usage Analytics
126

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

129
```python { .api }
130
async def get_search_volume(
131
    self,
132
    index: str,
133
    start_date: str,
134
    end_date: str,
135
    tags: Optional[str] = None,
136
    request_options: Optional[Union[dict, RequestOptions]] = None
137
) -> GetSearchVolumeResponse:
138
    """
139
    Get search volume metrics over time.
140
    
141
    Parameters:
142
    - index: Index name to analyze
143
    - start_date: Start date (YYYY-MM-DD format)  
144
    - end_date: End date (YYYY-MM-DD format)
145
    - tags: Filter by specific tags
146
    - request_options: Additional request options
147
    
148
    Returns:
149
    GetSearchVolumeResponse with volume metrics
150
    """
151

152
async def get_searches_no_results(
153
    self,
154
    index: str, 
155
    start_date: str,
156
    end_date: str,
157
    limit: Optional[int] = None,
158
    offset: Optional[int] = None,
159
    tags: Optional[str] = None,
160
    request_options: Optional[Union[dict, RequestOptions]] = None
161
) -> GetSearchesNoResultsResponse:
162
    """
163
    Get searches that returned no results.
164
    
165
    Parameters:
166
    - index: Index name to analyze
167
    - start_date: Start date (YYYY-MM-DD format)
168
    - end_date: End date (YYYY-MM-DD format)
169
    - limit: Maximum number of results to return
170
    - offset: Offset for pagination
171
    - tags: Filter by specific tags
172
    - request_options: Additional request options
173
    
174
    Returns:
175
    GetSearchesNoResultsResponse with zero-result queries
176
    """
177

178
async def get_searches_no_clicks(
179
    self,
180
    index: str,
181
    start_date: str, 
182
    end_date: str,
183
    limit: Optional[int] = None,
184
    offset: Optional[int] = None,
185
    tags: Optional[str] = None,
186
    request_options: Optional[Union[dict, RequestOptions]] = None
187
) -> GetSearchesNoClicksResponse:
188
    """
189
    Get searches that received no clicks.
190
    
191
    Parameters:
192
    - index: Index name to analyze
193
    - start_date: Start date (YYYY-MM-DD format)
194
    - end_date: End date (YYYY-MM-DD format)
195
    - limit: Maximum number of results to return
196
    - offset: Offset for pagination
197
    - tags: Filter by specific tags
198
    - request_options: Additional request options
199
    
200
    Returns:
201
    GetSearchesNoClicksResponse with zero-click queries
202
    """
203
```
204

205
### Top Searches and Popular Content
206

207
Identify trending searches and popular content to optimize user experience.
208

209
```python { .api }
210
async def get_top_searches(
211
    self,
212
    index: str,
213
    start_date: str,
214
    end_date: str,
215
    limit: Optional[int] = None,
216
    offset: Optional[int] = None,
217
    tags: Optional[str] = None,
218
    order_by: Optional[str] = None,
219
    direction: Optional[str] = None,
220
    request_options: Optional[Union[dict, RequestOptions]] = None
221
) -> GetTopSearchesResponse:
222
    """
223
    Get most popular search queries.
224
    
225
    Parameters:
226
    - index: Index name to analyze
227
    - start_date: Start date (YYYY-MM-DD format)
228
    - end_date: End date (YYYY-MM-DD format)
229
    - limit: Maximum number of results to return
230
    - offset: Offset for pagination
231
    - tags: Filter by specific tags
232
    - order_by: Sort field (searchCount, clickThroughRate, etc.)
233
    - direction: Sort direction (asc, desc)
234
    - request_options: Additional request options
235
    
236
    Returns:
237
    GetTopSearchesResponse with popular queries
238
    """
239

240
async def get_top_hits(
241
    self,
242
    index: str,
243
    start_date: str,
244
    end_date: str,
245
    limit: Optional[int] = None,
246
    offset: Optional[int] = None,
247
    tags: Optional[str] = None,
248
    request_options: Optional[Union[dict, RequestOptions]] = None
249
) -> GetTopHitsResponse:
250
    """
251
    Get most clicked search results.
252
    
253
    Parameters:
254
    - index: Index name to analyze
255
    - start_date: Start date (YYYY-MM-DD format)
256
    - end_date: End date (YYYY-MM-DD format)
257
    - limit: Maximum number of results to return
258
    - offset: Offset for pagination
259
    - tags: Filter by specific tags
260
    - request_options: Additional request options
261
    
262
    Returns:
263
    GetTopHitsResponse with popular results
264
    """
265

266
async def get_top_filters(
267
    self,
268
    index: str,
269
    start_date: str,
270
    end_date: str,
271
    limit: Optional[int] = None,
272
    offset: Optional[int] = None,
273
    tags: Optional[str] = None,
274
    request_options: Optional[Union[dict, RequestOptions]] = None
275
) -> GetTopFiltersResponse:
276
    """
277
    Get most used search filters.
278
    
279
    Parameters:
280
    - index: Index name to analyze
281
    - start_date: Start date (YYYY-MM-DD format)
282
    - end_date: End date (YYYY-MM-DD format)
283
    - limit: Maximum number of results to return
284
    - offset: Offset for pagination
285
    - tags: Filter by specific tags
286
    - request_options: Additional request options
287
    
288
    Returns:
289
    GetTopFiltersResponse with popular filters
290
    """
291
```
292

293
### Revenue and User Analytics
294

295
Track revenue attribution and user engagement metrics.
296

297
```python { .api }
298
async def get_revenue(
299
    self,
300
    index: str,
301
    start_date: str,
302
    end_date: str,
303
    tags: Optional[str] = None,
304
    request_options: Optional[Union[dict, RequestOptions]] = None
305
) -> GetRevenueResponse:
306
    """
307
    Get revenue metrics attributed to search.
308
    
309
    Parameters:
310
    - index: Index name to analyze
311
    - start_date: Start date (YYYY-MM-DD format)
312
    - end_date: End date (YYYY-MM-DD format)
313
    - tags: Filter by specific tags
314
    - request_options: Additional request options
315
    
316
    Returns:
317
    GetRevenueResponse with revenue data
318
    """
319

320
async def get_users_count(
321
    self,
322
    index: str,
323
    start_date: str,
324
    end_date: str,
325
    tags: Optional[str] = None,
326
    request_options: Optional[Union[dict, RequestOptions]] = None
327
) -> GetUsersCountResponse:
328
    """
329
    Get unique user count metrics.
330
    
331
    Parameters:
332
    - index: Index name to analyze
333
    - start_date: Start date (YYYY-MM-DD format)
334
    - end_date: End date (YYYY-MM-DD format)
335
    - tags: Filter by specific tags
336
    - request_options: Additional request options
337
    
338
    Returns:
339
    GetUsersCountResponse with user metrics
340
    """
341

342
async def get_top_countries(
343
    self,
344
    index: str,
345
    start_date: str,
346
    end_date: str,
347
    limit: Optional[int] = None,
348
    offset: Optional[int] = None,
349
    tags: Optional[str] = None,
350
    request_options: Optional[Union[dict, RequestOptions]] = None
351
) -> GetTopCountriesResponse:
352
    """
353
    Get top countries by search usage.
354
    
355
    Parameters:
356
    - index: Index name to analyze
357
    - start_date: Start date (YYYY-MM-DD format)
358
    - end_date: End date (YYYY-MM-DD format)
359
    - limit: Maximum number of results to return
360
    - offset: Offset for pagination
361
    - tags: Filter by specific tags
362
    - request_options: Additional request options
363
    
364
    Returns:
365
    GetTopCountriesResponse with country metrics
366
    """
367
```
368

369
### Insights Client
370

371
Track user behavior and interaction events for personalization and analytics.
372

373
```python { .api }
374
class InsightsClient:
375
    def __init__(
376
        self,
377
        app_id: Optional[str] = None,
378
        api_key: Optional[str] = None,
379
        transporter: Optional[Transporter] = None,
380
        config: Optional[InsightsConfig] = None
381
    ) -> None: ...
382

383
    @classmethod
384
    def create_with_config(
385
        cls, 
386
        config: InsightsConfig, 
387
        transporter: Optional[Transporter] = None
388
    ) -> InsightsClient: ...
389

390
    async def close(self) -> None: ...
391
    async def set_client_api_key(self, api_key: str) -> None: ...
392
```
393

394
### Event Tracking
395

396
Track user interactions for personalization and analytics.
397

398
```python { .api }
399
async def push_events(
400
    self,
401
    insights_events: Union[InsightsEvents, dict],
402
    request_options: Optional[Union[dict, RequestOptions]] = None
403
) -> EventsResponse:
404
    """
405
    Push user interaction events to Algolia.
406
    
407
    Parameters:
408
    - insights_events: Events data to track
409
    - request_options: Additional request options
410
    
411
    Returns:
412
    EventsResponse with processing confirmation
413
    """
414

415
async def click_through_events(
416
    self,
417
    click_through_events: Union[ClickThroughEvents, dict],
418
    request_options: Optional[Union[dict, RequestOptions]] = None
419
) -> EventsResponse:
420
    """
421
    Track click-through events on search results.
422
    
423
    Parameters:
424
    - click_through_events: Click event data
425
    - request_options: Additional request options
426
    
427
    Returns:
428
    EventsResponse with processing confirmation
429
    """
430

431
async def conversion_events(
432
    self,
433
    conversion_events: Union[ConversionEvents, dict],
434
    request_options: Optional[Union[dict, RequestOptions]] = None
435
) -> EventsResponse:
436
    """
437
    Track conversion events (purchases, signups, etc.).
438
    
439
    Parameters:
440
    - conversion_events: Conversion event data
441
    - request_options: Additional request options
442
    
443
    Returns:
444
    EventsResponse with processing confirmation
445
    """
446

447
async def purchase_events(
448
    self,
449
    purchase_events: Union[PurchaseEvents, dict],
450
    request_options: Optional[Union[dict, RequestOptions]] = None
451
) -> EventsResponse:
452
    """
453
    Track purchase events with revenue data.
454
    
455
    Parameters:
456
    - purchase_events: Purchase event data
457
    - request_options: Additional request options
458
    
459
    Returns:
460
    EventsResponse with processing confirmation
461
    """
462

463
async def view_events(
464
    self,
465
    view_events: Union[ViewEvents, dict],
466
    request_options: Optional[Union[dict, RequestOptions]] = None
467
) -> EventsResponse:
468
    """
469
    Track view events on content or products.
470
    
471
    Parameters:
472
    - view_events: View event data
473
    - request_options: Additional request options
474
    
475
    Returns:
476
    EventsResponse with processing confirmation
477
    """
478
```
479

480
### User Profile Management
481

482
Manage user profiles and behavioral data.
483

484
```python { .api }
485
async def get_user_profile(
486
    self,
487
    user_token: str,
488
    request_options: Optional[Union[dict, RequestOptions]] = None
489
) -> GetUserProfileResponse:
490
    """
491
    Get user profile and behavioral data.
492
    
493
    Parameters:
494
    - user_token: Unique user identifier
495
    - request_options: Additional request options
496
    
497
    Returns:
498
    GetUserProfileResponse with user data
499
    """
500

501
async def delete_user_profile(
502
    self,
503
    user_token: str,
504
    request_options: Optional[Union[dict, RequestOptions]] = None
505
) -> dict:
506
    """
507
    Delete a user profile and all associated data.
508
    
509
    Parameters:
510
    - user_token: Unique user identifier
511
    - request_options: Additional request options
512
    
513
    Returns:
514
    Deletion confirmation response
515
    """
516
```
517

518
## Usage Examples
519

520
### Track User Interactions
521

522
```python
523
from algoliasearch.insights.client import InsightsClient
524

525
# Initialize client
526
client = InsightsClient("YOUR_APP_ID", "YOUR_API_KEY")
527

528
# Track click event
529
response = await client.click_through_events({
530
    "events": [{
531
        "eventType": "click",
532
        "eventName": "Product Clicked",
533
        "index": "products",
534
        "userToken": "user-123",
535
        "timestamp": int(time.time() * 1000),
536
        "objectIDs": ["product-456"],
537
        "positions": [1],
538
        "queryID": "query-789"
539
    }]
540
})
541

542
# Track conversion event
543
response = await client.conversion_events({
544
    "events": [{
545
        "eventType": "conversion", 
546
        "eventName": "Purchase",
547
        "index": "products",
548
        "userToken": "user-123",
549
        "timestamp": int(time.time() * 1000),
550
        "objectIDs": ["product-456"],
551
        "queryID": "query-789"
552
    }]
553
})
554
```
555

556
### Analyze Search Performance
557

558
```python
559
from algoliasearch.analytics.client import AnalyticsClient
560
from datetime import datetime, timedelta
561

562
# Initialize client
563
client = AnalyticsClient("YOUR_APP_ID", "YOUR_API_KEY")
564

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

569
# Get click-through rate
570
ctr_response = await client.get_click_through_rate(
571
    index="products",
572
    start_date=start_date,
573
    end_date=end_date
574
)
575

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

578
# Get top searches
579
top_searches = await client.get_top_searches(
580
    index="products",
581
    start_date=start_date,
582
    end_date=end_date,
583
    limit=10
584
)
585

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

590
## Types
591

592
```python { .api }
593
# Analytics response types
594
class GetClickThroughRateResponse(BaseModel):
595
    rate: float
596
    click_count: int
597
    search_count: int
598
    dates: List[dict]
599

600
class GetConversionRateResponse(BaseModel):
601
    rate: float
602
    conversion_count: int
603
    click_count: int
604
    dates: List[dict]
605

606
class GetTopSearchesResponse(BaseModel):
607
    searches: List[dict]
608
    count: int
609

610
class GetRevenueResponse(BaseModel):
611
    revenue: dict
612
    dates: List[dict]
613

614
# Insights event types
615
class InsightsEvents(BaseModel):
616
    events: List[InsightsEvent]
617

618
class InsightsEvent(BaseModel):
619
    event_type: str
620
    event_name: str
621
    index: str
622
    user_token: str
623
    timestamp: Optional[int] = None
624
    object_ids: Optional[List[str]] = None
625
    positions: Optional[List[int]] = None
626
    query_id: Optional[str] = None
627

628
class EventsResponse(BaseModel):
629
    status: int
630
    message: str
631

632
class GetUserProfileResponse(BaseModel):
633
    user_token: str
634
    last_event_at: str
635
    clusters: Optional[dict] = None
636
    personalization: Optional[dict] = None
637
```