0
# Algoliasearch
1

2
A fully-featured and blazing-fast Python API client to interact with Algolia's search-as-a-service platform. This comprehensive client provides access to Algolia's full suite of services including search, recommendations, analytics, A/B testing, data ingestion, insights, monitoring, personalization, and query suggestions.
3

4
## Package Information
5

6
- **Package Name**: algoliasearch
7
- **Language**: Python
8
- **Installation**: `pip install 'algoliasearch>=4.0,<5.0'`
9
- **Python Version**: 3.8+
10

11
## Core Imports
12

13
```python
14
from algoliasearch.search.client import SearchClient
15
```
16

17
For other services:
18

19
```python
20
from algoliasearch.recommend.client import RecommendClient
21
from algoliasearch.analytics.client import AnalyticsClient
22
from algoliasearch.insights.client import InsightsClient
23
from algoliasearch.abtesting.client import AbtestingClient
24
from algoliasearch.ingestion.client import IngestionClient
25
from algoliasearch.monitoring.client import MonitoringClient
26
from algoliasearch.personalization.client import PersonalizationClient
27
from algoliasearch.query_suggestions.client import QuerySuggestionsClient
28
from algoliasearch.composition.client import CompositionClient
29
```
30

31
## Basic Usage
32

33
```python
34
from algoliasearch.search.client import SearchClient
35

36
# Initialize client
37
client = SearchClient("YOUR_APP_ID", "YOUR_API_KEY")
38

39
# Save an object to an index
40
response = await client.save_object(
41
    index_name="products",
42
    body={
43
        "objectID": "123",
44
        "name": "Blue T-Shirt",
45
        "brand": "Fashion Co",
46
        "price": 29.99
47
    }
48
)
49

50
# Wait for the indexing task to complete
51
await client.wait_for_task(index_name="products", task_id=response.task_id)
52

53
# Search for products
54
response = await client.search(
55
    search_method_params={
56
        "requests": [{
57
            "indexName": "products",
58
            "query": "blue shirt",
59
            "hitsPerPage": 10
60
        }]
61
    }
62
)
63

64
# Print results
65
for hit in response.results[0].hits:
66
    print(f"{hit['name']} - ${hit['price']}")
67
```
68

69
## Architecture
70

71
The Algoliasearch Python client is built with a service-oriented architecture:
72

73
- **Service Clients**: Each Algolia service (search, analytics, etc.) has dedicated async and sync client classes
74
- **Auto-Generated Code**: All client code is generated from OpenAPI specifications to ensure API compatibility
75
- **HTTP Transport Layer**: Configurable HTTP transporters handle requests/responses with automatic retries
76
- **Pydantic Models**: Type-safe request/response models with validation
77
- **Dual Interface**: Both asynchronous (asyncio/aiohttp) and synchronous (requests) interfaces
78

79
## Capabilities
80

81
### Search Operations
82

83
Core search functionality including index management, object operations, search queries, rules, synonyms, and API key management. This is the primary interface for most Algolia operations.
84

85
```python { .api }
86
class SearchClient:
87
    def __init__(self, app_id: str = None, api_key: str = None): ...
88
    async def search(self, search_method_params: SearchMethodParams) -> SearchResponse: ...
89
    async def save_object(self, index_name: str, body: dict) -> SaveObjectResponse: ...
90
    async def save_objects(self, index_name: str, objects: List[dict]) -> BatchResponse: ...
91
    async def delete_object(self, index_name: str, object_id: str) -> DeletedAtResponse: ...
92
    async def get_object(self, index_name: str, object_id: str) -> dict: ...
93
    async def browse_objects(self, index_name: str, browse_params: BrowseParams = None) -> BrowseResponse: ...
94
```
95

96
[Search Operations](./search-operations.md)
97

98
### Recommendations
99

100
AI-powered recommendation engine for suggesting relevant content, products, or related items based on user behavior and content similarity.
101

102
```python { .api }
103
class RecommendClient:
104
    def __init__(self, app_id: str = None, api_key: str = None): ...
105
    async def get_recommendations(self, get_recommendations_params: GetRecommendationsParams) -> GetRecommendationsResponse: ...
106
    async def search_recommend_rules(self, index_name: str, search_recommend_rules_params: SearchRecommendRulesParams = None) -> SearchRecommendRulesResponse: ...
107
```
108

109
[Recommendations](./recommendations.md)
110

111
### Analytics and Insights
112

113
Comprehensive analytics for search performance, user behavior tracking, and business insights including click-through rates, conversion metrics, and user interaction data.
114

115
```python { .api }
116
class AnalyticsClient:
117
    def __init__(self, app_id: str = None, api_key: str = None): ...
118
    async def get_click_through_rate(self, index: str, **kwargs) -> GetClickThroughRateResponse: ...
119
    async def get_conversion_rate(self, index: str, **kwargs) -> GetConversionRateResponse: ...
120
    async def get_search_volume(self, index: str, **kwargs) -> GetSearchVolumeResponse: ...
121

122
class InsightsClient:
123
    def __init__(self, app_id: str = None, api_key: str = None): ...
124
    async def push_events(self, insights_events: InsightsEvents) -> EventsResponse: ...
125
    async def click_through_events(self, click_through_events: ClickThroughEvents) -> EventsResponse: ...
126
```
127

128
[Analytics and Insights](./analytics-insights.md)
129

130
### A/B Testing
131

132
Controlled experimentation platform for testing search configurations, UI changes, and business strategies with statistical significance.
133

134
```python { .api }
135
class AbtestingClient:
136
    def __init__(self, app_id: str = None, api_key: str = None): ...
137
    async def list_ab_tests(self, **kwargs) -> ListABTestsResponse: ...
138
    async def get_ab_test(self, id: int) -> ABTest: ...
139
    async def add_ab_test(self, ab_test_create: ABTestCreate) -> ABTestResponse: ...
140
    async def stop_ab_test(self, id: int) -> ABTestResponse: ...
141
```
142

143
[A/B Testing](./ab-testing.md)
144

145
### Data Ingestion
146

147
Scalable data pipeline services for importing, transforming, and synchronizing large datasets from various sources into Algolia indices.
148

149
```python { .api }
150
class IngestionClient:
151
    def __init__(self, app_id: str = None, api_key: str = None): ...
152
    async def list_sources(self, **kwargs) -> ListSourcesResponse: ...
153
    async def create_source(self, source_create: SourceCreate) -> Source: ...
154
    async def list_transformations(self, **kwargs) -> ListTransformationsResponse: ...
155
    async def create_transformation(self, transformation_create: TransformationCreate) -> Transformation: ...
156
```
157

158
[Data Ingestion](./data-ingestion.md)
159

160
### Monitoring and Management
161

162
Service health monitoring, infrastructure metrics, and operational management tools for maintaining optimal search performance.
163

164
```python { .api }
165
class MonitoringClient:
166
    def __init__(self, app_id: str = None, api_key: str = None): ...
167
    async def get_cluster_status(self, **kwargs) -> ClusterStatus: ...
168
    async def get_infrastructure_metrics(self, **kwargs) -> InfrastructureMetrics: ...
169

170
class PersonalizationClient:
171
    def __init__(self, app_id: str = None, api_key: str = None): ...
172
    async def get_personalization_strategy(self, **kwargs) -> PersonalizationStrategy: ...
173
    async def set_personalization_strategy(self, personalization_strategy_params: PersonalizationStrategyParams) -> SetPersonalizationStrategyResponse: ...
174
```
175

176
[Monitoring and Management](./monitoring-management.md)
177

178
### Query Suggestions
179

180
Intelligent query completion and suggestion services that help users discover relevant search terms and improve search experience.
181

182
```python { .api }
183
class QuerySuggestionsClient:
184
    def __init__(self, app_id: str = None, api_key: str = None): ...
185
    async def list_configs(self, **kwargs) -> ListConfigsResponse: ...
186
    async def create_config(self, configuration_with_index: ConfigurationWithIndex) -> BaseResponse: ...
187
    async def get_config_status(self, index_name: str) -> GetConfigStatusResponse: ...
188
```
189

190
[Query Suggestions](./query-suggestions.md)
191

192
## Common Types
193

194
```python { .api }
195
from typing import Dict, List, Optional, Union, Any
196
from pydantic import BaseModel
197

198
# Core response types
199
class ApiResponse(BaseModel):
200
    def deserialize(self, response_type: type, data: str): ...
201
    def to_json(self) -> str: ...
202

203
# Request options for all methods
204
class RequestOptions(BaseModel):
205
    headers: Optional[Dict[str, str]] = None
206
    query_params: Optional[Dict[str, Any]] = None
207
    timeout: Optional[int] = None
208

209
# Authentication and configuration
210
class BaseConfig(BaseModel):
211
    app_id: str
212
    api_key: str
213
    hosts: Optional[List[str]] = None
214

215
# Task tracking for async operations
216
class GetTaskResponse(BaseModel):
217
    task_id: int
218
    status: str
219
    pending_task: bool
220

221
# Common batch operation response
222
class BatchResponse(BaseModel):
223
    task_id: int
224
    object_ids: List[str]
225
```