0
# Recommendations
1

2
AI-powered recommendation engine for suggesting relevant content, products, or related items based on user behavior and content similarity. The Recommend API provides personalized suggestions to enhance user experience and drive engagement.
3

4
## Capabilities
5

6
### Client Initialization
7

8
Create recommendation clients for both async and sync operations.
9

10
```python { .api }
11
class RecommendClient:
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[RecommendConfig] = None
18
    ) -> None: ...
19

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

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

30
class RecommendClientSync:
31
    def __init__(
32
        self,
33
        app_id: Optional[str] = None,
34
        api_key: Optional[str] = None,
35
        transporter: Optional[TransporterSync] = None,
36
        config: Optional[RecommendConfig] = None
37
    ) -> None: ...
38
```
39

40
### Get Recommendations
41

42
Retrieve personalized recommendations based on user behavior, content similarity, or custom strategies.
43

44
```python { .api }
45
async def get_recommendations(
46
    self,
47
    get_recommendations_params: Union[GetRecommendationsParams, dict],
48
    request_options: Optional[Union[dict, RequestOptions]] = None
49
) -> GetRecommendationsResponse:
50
    """
51
    Get personalized recommendations for users or items.
52
    
53
    Parameters:
54
    - get_recommendations_params: Recommendation request configuration
55
    - request_options: Additional request options
56
    
57
    Returns:
58
    GetRecommendationsResponse with recommended items
59
    """
60
```
61

62
### Recommendation Rules Management
63

64
Manage recommendation rules that control how suggestions are generated and filtered.
65

66
```python { .api }
67
async def search_recommend_rules(
68
    self,
69
    index_name: str,
70
    search_recommend_rules_params: Optional[Union[SearchRecommendRulesParams, dict]] = None,
71
    request_options: Optional[Union[dict, RequestOptions]] = None
72
) -> SearchRecommendRulesResponse:
73
    """
74
    Search for recommendation rules in an index.
75
    
76
    Parameters:
77
    - index_name: Target index name
78
    - search_recommend_rules_params: Search parameters for rules
79
    - request_options: Additional request options
80
    
81
    Returns:
82
    SearchRecommendRulesResponse with matching rules
83
    """
84

85
async def get_recommend_rule(
86
    self,
87
    index_name: str,
88
    model: str,
89
    object_id: str,
90
    request_options: Optional[Union[dict, RequestOptions]] = None
91
) -> RecommendRule:
92
    """
93
    Get a specific recommendation rule.
94
    
95
    Parameters:
96
    - index_name: Target index name
97
    - model: Recommendation model identifier
98
    - object_id: Rule identifier
99
    - request_options: Additional request options
100
    
101
    Returns:
102
    RecommendRule object
103
    """
104

105
async def create_recommend_rule(
106
    self,
107
    index_name: str,
108
    model: str,
109
    recommend_rule: Union[RecommendRule, dict],
110
    request_options: Optional[Union[dict, RequestOptions]] = None
111
) -> RecommendUpdatedAtResponse:
112
    """
113
    Create a new recommendation rule.
114
    
115
    Parameters:
116
    - index_name: Target index name
117
    - model: Recommendation model identifier
118
    - recommend_rule: Rule configuration
119
    - request_options: Additional request options
120
    
121
    Returns:
122
    RecommendUpdatedAtResponse with creation confirmation
123
    """
124

125
async def update_recommend_rule(
126
    self,
127
    index_name: str,
128
    model: str,
129
    object_id: str,
130
    recommend_rule: Union[RecommendRule, dict],
131
    request_options: Optional[Union[dict, RequestOptions]] = None
132
) -> RecommendUpdatedAtResponse:
133
    """
134
    Update an existing recommendation rule.
135
    
136
    Parameters:
137
    - index_name: Target index name
138
    - model: Recommendation model identifier
139
    - object_id: Rule identifier
140
    - recommend_rule: Updated rule configuration
141
    - request_options: Additional request options
142
    
143
    Returns:
144
    RecommendUpdatedAtResponse with update confirmation
145
    """
146

147
async def delete_recommend_rule(
148
    self,
149
    index_name: str,
150
    model: str,
151
    object_id: str,
152
    request_options: Optional[Union[dict, RequestOptions]] = None
153
) -> RecommendUpdatedAtResponse:
154
    """
155
    Delete a recommendation rule.
156
    
157
    Parameters:
158
    - index_name: Target index name
159
    - model: Recommendation model identifier
160
    - object_id: Rule identifier to delete
161
    - request_options: Additional request options
162
    
163
    Returns:
164
    RecommendUpdatedAtResponse with deletion confirmation
165
    """
166

167
async def batch_recommend_rules(
168
    self,
169
    index_name: str,
170
    model: str,
171
    batch_write_params: Union[BatchWriteParams, dict],
172
    request_options: Optional[Union[dict, RequestOptions]] = None
173
) -> RecommendUpdatedAtResponse:
174
    """
175
    Perform batch operations on recommendation rules.
176
    
177
    Parameters:
178
    - index_name: Target index name
179
    - model: Recommendation model identifier
180
    - batch_write_params: Batch operations to perform
181
    - request_options: Additional request options
182
    
183
    Returns:
184
    RecommendUpdatedAtResponse with batch operation confirmation
185
    """
186

187
async def get_recommend_status(
188
    self,
189
    index_name: str,
190
    model: str,
191
    request_options: Optional[Union[dict, RequestOptions]] = None
192
) -> GetRecommendStatusResponse:
193
    """
194
    Get the status of recommendation model for an index.
195
    
196
    Parameters:
197
    - index_name: Target index name
198
    - model: Recommendation model identifier
199
    - request_options: Additional request options
200
    
201
    Returns:
202
    GetRecommendStatusResponse with model status information
203
    """
204
```
205

206
### Custom API Endpoints
207

208
Execute custom HTTP operations for advanced recommendation features.
209

210
```python { .api }
211
async def custom_delete(
212
    self,
213
    path: str,
214
    parameters: Optional[Dict[str, Any]] = None,
215
    request_options: Optional[Union[dict, RequestOptions]] = None
216
) -> dict:
217
    """
218
    Perform a custom DELETE request.
219
    
220
    Parameters:
221
    - path: API endpoint path
222
    - parameters: Query parameters
223
    - request_options: Additional request options
224
    
225
    Returns:
226
    Response data as dictionary
227
    """
228

229
async def custom_get(
230
    self,
231
    path: str,
232
    parameters: Optional[Dict[str, Any]] = None,
233
    request_options: Optional[Union[dict, RequestOptions]] = None
234
) -> dict:
235
    """
236
    Perform a custom GET request.
237
    
238
    Parameters:
239
    - path: API endpoint path
240
    - parameters: Query parameters
241
    - request_options: Additional request options
242
    
243
    Returns:
244
    Response data as dictionary
245
    """
246

247
async def custom_post(
248
    self,
249
    path: str,
250
    parameters: Optional[Dict[str, Any]] = None,
251
    body: Optional[Dict[str, Any]] = None,
252
    request_options: Optional[Union[dict, RequestOptions]] = None
253
) -> dict:
254
    """
255
    Perform a custom POST request.
256
    
257
    Parameters:
258
    - path: API endpoint path
259
    - parameters: Query parameters
260
    - body: Request body data
261
    - request_options: Additional request options
262
    
263
    Returns:
264
    Response data as dictionary
265
    """
266

267
async def custom_put(
268
    self,
269
    path: str,
270
    parameters: Optional[Dict[str, Any]] = None,
271
    body: Optional[Dict[str, Any]] = None,
272
    request_options: Optional[Union[dict, RequestOptions]] = None
273
) -> dict:
274
    """
275
    Perform a custom PUT request.
276
    
277
    Parameters:
278
    - path: API endpoint path
279
    - parameters: Query parameters
280
    - body: Request body data
281
    - request_options: Additional request options
282
    
283
    Returns:
284
    Response data as dictionary
285
    """
286
```
287

288
## Usage Examples
289

290
### Basic Recommendations
291

292
```python
293
from algoliasearch.recommend.client import RecommendClient
294

295
# Initialize client
296
client = RecommendClient("YOUR_APP_ID", "YOUR_API_KEY")
297

298
# Get related products recommendations
299
response = await client.get_recommendations({
300
    "requests": [{
301
        "indexName": "products",
302
        "model": "related-products", 
303
        "objectID": "product-123",
304
        "maxRecommendations": 10
305
    }]
306
})
307

308
# Process recommendations
309
for hit in response.results[0].hits:
310
    print(f"Recommended: {hit['name']} - Score: {hit.get('_score', 'N/A')}")
311
```
312

313
### Trending Items
314

315
```python
316
# Get trending items
317
response = await client.get_recommendations({
318
    "requests": [{
319
        "indexName": "products",
320
        "model": "trending-items",
321
        "maxRecommendations": 20,
322
        "facetFilters": [
323
            "category:electronics"
324
        ]
325
    }]
326
})
327
```
328

329
### Frequently Bought Together
330

331
```python
332
# Get frequently bought together recommendations
333
response = await client.get_recommendations({
334
    "requests": [{
335
        "indexName": "products", 
336
        "model": "bought-together",
337
        "objectID": "product-456",
338
        "maxRecommendations": 5
339
    }]
340
})
341
```
342

343
## Types
344

345
```python { .api }
346
# Recommendation request types
347
class GetRecommendationsParams(BaseModel):
348
    requests: List[RecommendationsRequest]
349

350
class RecommendationsRequest(BaseModel):
351
    index_name: str
352
    model: str
353
    object_id: Optional[str] = None
354
    max_recommendations: Optional[int] = None
355
    query_parameters: Optional[dict] = None
356
    facet_filters: Optional[List[str]] = None
357
    numeric_filters: Optional[List[str]] = None
358
    filters: Optional[str] = None
359
    user_token: Optional[str] = None
360

361
# Response types
362
class GetRecommendationsResponse(BaseModel):
363
    results: List[RecommendationsResult]
364

365
class RecommendationsResult(BaseModel):
366
    hits: List[dict]
367
    nb_hits: int
368
    processing_time_ms: int
369
    query: Optional[str] = None
370
    params: Optional[str] = None
371

372
# Rule types  
373
class RecommendRule(BaseModel):
374
    object_id: str
375
    condition: dict
376
    consequence: dict
377
    description: Optional[str] = None
378
    enabled: Optional[bool] = None
379

380
class SearchRecommendRulesParams(BaseModel):
381
    query: Optional[str] = None
382
    anchoring: Optional[str] = None
383
    context: Optional[str] = None
384
    page: Optional[int] = None
385
    hits_per_page: Optional[int] = None
386
    enabled: Optional[bool] = None
387

388
class SearchRecommendRulesResponse(BaseModel):
389
    hits: List[RecommendRule]
390
    nb_hits: int
391
    page: int
392
    nb_pages: int
393
    hits_per_page: int
394

395
class RecommendUpdatedAtResponse(BaseModel):
396
    task_id: int
397
    updated_at: str
398

399
class GetRecommendStatusResponse(BaseModel):
400
    is_running: bool
401
    processing_time_ms: Optional[int] = None
402
    last_built_at: Optional[str] = None
403
    nb_records: Optional[int] = None
404
```
405

406
## Recommendation Models
407

408
The Recommend API supports several built-in recommendation models:
409

410
- **related-products**: Items similar to a given product
411
- **bought-together**: Items frequently purchased together
412
- **trending-items**: Popular items based on user interactions
413
- **looking-similar**: Visually or contextually similar items
414

415
Each model can be customized with filters, query parameters, and business rules to fine-tune recommendation quality and relevance.