Update the Python API client

This is documentation for v3 of the Python API clients, which is not the latest version. To see the documentation for the latest version, see Python v4.

You should keep your Python API client up to date to benefit from improvements and bug fixes.

The Python API client follows Semantic Versioning.

Upgrade to version 3.0.0

From version 2.x.x

This document lists every known breaking change:

  • Remove support for Python 2
  • Add support for Python 3.9 and above
  • Remove deprecated RecommendationClient, use the PersonalizationClient instead

Update your algoliasearch dependency to >=3.0,<4.0 using pip:

$
python -m pip install --upgrade 'algoliasearch>=3.0,<4.0'

Then, update your requirements in your setup.py or requirements.txt to: algoliasearch>=3.0,<4.0.

From version 1.x.x

Follow the Upgrade from 1.20.0 to 2.0.0 and From versions 2.x.x guides.

Upgrade from 1.20.0 to 2.0.0

This document lists every known breaking change. Not all these changes may affect your application, since some of these breaking changes happen in obscure parts of the client.

Update your algoliasearch dependency to >=2.0,<3.0 using pip:

$
python -m pip install --upgrade 'algoliasearch>=2.0,<3.0'

Then, update your requirements in your setup.py or requirements.txt to: algoliasearch>=2.0,<3.0.

SearchClient

You can initialize the SearchClient as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- client = Client('app_id', 'api_key')

+ from algoliasearch.search_client import SearchClient
+ client = SearchClient.create('app_id', 'api_key')
List of method signature changes
1.20.0 Breaking Change 2.0.0
addUserKey(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0, indexes=None) Removed, use add_api_key instead add_api_key(acl, request_options=None)
add_api_key(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0, indexes=None, request_options=None) Changed add_api_key(acl, request_options=None)
add_user_key(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0, indexes=None) Removed, use add_api_key instead add_api_key(acl, request_options=None)
batch(requests, request_options=None) Removed, use multiple_batch instead multiple_batch(operations, request_options=None)
copyIndex(src_index_name, dst_index_name) Removed, use copy_index instead copy_index(src_index_name, dst_index_name, request_options=None)
copy_index(src_index_name, dst_index_name, request_options=None, scope=None) Changed copy_index(src_index_name, dst_index_name, request_options=None)
deleteIndex(index_name) Removed, use init_index('name').delete() instead delete(request_options=None)
deleteUserKey(api_key) Removed, use delete_api_key instead delete_api_key(key, request_options=None)
delete_api_key(api_key, request_options=None) Changed delete_api_key(key, request_options=None)
delete_index(index_name, request_options=None) Removed, use init_index('name').delete() instead delete(request_options=None)
delete_user_key(api_key) Removed, use delete_api_key instead delete_api_key(key, request_options=None)
disableRateLimitForward() Removed, use RequestOptions param instead  
disable_rate_limit_forward() Removed, use RequestOptions param instead  
enableRateLimitForward(admin_api_key, end_user_ip, rate_limit_api_key) Removed, use RequestOptions param instead  
enable_rate_limit_forward(end_user_ip, rate_limit_api_key) Removed, use RequestOptions param instead  
generateSecuredApiKey(private_api_key, tag_filters, user_token='') Removed, use generate_secured_api_key instead generate_secured_api_key(parent_api_key, restrictions)
generate_secured_api_key(private_api_key, queryParameters, user_token='') Changed generate_secured_api_key(parent_api_key, restrictions)
getLogs(offset=0, length=10, type='all') Removed, use get_logs instead get_logs(request_options=None)
getUserKeyACL(api_key) Removed, use get_api_key instead get_api_key(key, request_options=None)
get_api_key(api_key, request_options=None) Changed get_api_key(key, request_options=None)
get_api_key_acl(api_key, request_options=None) Removed, use get_api_key instead get_api_key(key, request_options=None)
get_logs(offset=0, length=10, type='all', request_options=None) Changed get_logs(request_options=None)
get_task(index_name, task_id, request_options=None) Removed, use init_index('name').get_task instead get_task(task_id, request_options=None)
get_top_user_id(request_options=None) Removed, use get_top_user_ids instead get_top_user_ids(request_options=None)
get_user_key_acl(api_key) Removed, use get_api_key instead get_api_key(key, request_options=None)
initIndex(index_name) Removed, use init_index instead init_index(name)
init_analytics() Removed, use AnalyticsClient.create instead create(app_id=None, api_key=None, region=None)
init_index(index_name) Changed init_index(name)
init_insights_client(region='us') Removed, use InsightsClient.create instead create(app_id=None, api_key=None, region=None)
is_alive(request_options=None) Removed  
is_task_published(index_name, task_id, request_options=None) Removed  
listIndexes() Removed, use list_indices instead list_indices(request_options=None)
listUserKeys() Removed, use list_api_keys instead list_api_keys(request_options=None)
list_indexes(request_options=None) Removed, use list_indices instead list_indices(request_options=None)
list_user_ids(page=0, hits_per_page=20, request_options=None) Changed list_user_ids(request_options=None)
list_user_keys() Removed, use list_api_keys instead list_api_keys(request_options=None)
moveIndex(src_index_name, dst_index_name) Removed, use move_index instead move_index(src_index_name, dst_index_name, request_options=None)
multipleQueries(queries, index_name_key='indexName') Removed, use multiple_queries instead multiple_queries(queries, request_options=None)
multiple_queries(queries, index_name_key='indexName', strategy='none', request_options=None) Changed multiple_queries(queries, request_options=None)
restore_api_key(api_key, request_options=None) Changed restore_api_key(key, request_options=None)
search_user_ids(query, cluster=None, page=None, hits_per_page=None, request_options=None) Changed search_user_ids(query, request_options=None)
set_end_user_ip(end_user_ip) Removed, use RequestOptions param instead  
set_extra_header(key, value) Removed, use RequestOptions param instead  
set_extra_headers(**kwargs) Removed, use RequestOptions param instead  
set_timeout(connect_timeout, read_timeout, search_timeout=5) Removed, use RequestOptions param instead  
update_api_key(api_key, obj, validity=None, max_queries_per_ip_per_hour=None, max_hits_per_query=None, indexes=None, request_options=None) Changed update_api_key(key, request_options=None)
update_user_key(api_key, obj, validity=None, max_queries_per_ip_per_hour=None, max_hits_per_query=None, indexes=None) Removed, use update_api_key instead update_api_key(key, request_options=None)
wait_task(index_name, task_id, time_before_retry=100, request_options=None) Removed, use init_index('name').wait_task instead wait_task(task_id, request_options=None)

SearchIndex

You can initialize the SearchIndex as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- index = Client('app_id', 'api_key').init_index('name')

+ from algoliasearch.search_client import SearchClient
+ index = SearchClient.create('app_id', 'api_key').init_index('name')
List of method signature changes
1.20.0 Breaking Change 2.0.0
addObject(content, object_id=None) Removed, use save_object instead save_object(obj, request_options=None)
addObjects(objects) Removed, use save_objects instead save_objects(objects, request_options=None)
addUserKey(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0) Removed, use SearchClient.add_api_key instead add_api_key(acl, request_options=None)
add_api_key(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0, request_options=None) Removed, use SearchClient.add_api_key instead add_api_key(acl, request_options=None)
add_object(content, object_id=None, request_options=None) Removed, use save_object instead save_object(obj, request_options=None)
add_objects(objects, request_options=None) Removed, use save_objects instead save_objects(objects, request_options=None)
add_user_key(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0) Removed, use SearchClient.add_api_key instead add_api_key(acl, request_options=None)
batch(requests, no_create=False, request_options=None) Changed batch(requests, request_options=None)
batch_rules(rules, forward_to_replicas=False, clear_existing_rules=False, request_options=None) Removed, use save_rules instead save_rules(rules, request_options=None)
batch_synonyms(synonyms, forward_to_slaves=False, replace_existing_synonyms=False, forward_to_replicas=False, request_options=None) Removed, use save_synonyms instead save_synonyms(synonyms, request_options=None)
browse(page=0, hits_per_page=1000) Removed, use browse_objects instead browse_objects(request_options=None)
browse_all(params=None, request_options=None) Removed, use browse_objects instead browse_objects(request_options=None)
browse_from(params=None, cursor=None, request_options=None) Removed, use browse_objects instead browse_objects(request_options=None)
clearIndex() Removed, use clear_objects instead clear_objects(request_options=None)
clear_index(request_options=None) Removed, use clear_objects instead clear_objects(request_options=None)
clear_rules(forward_to_replicas=False, request_options=None) Changed clear_rules(request_options=None)
clear_synonyms(forward_to_slaves=False, forward_to_replicas=False, request_options=None) Changed clear_synonyms(request_options=None)
deleteByQuery(query, params=None) Removed, use delete_by instead delete_by(filters, request_options=None)
deleteObject(object_id) Removed, use delete_object instead delete_object(object_id, request_options=None)
deleteObjects(objects) Removed, use delete_objects instead delete_objects(object_ids, request_options=None)
deleteUserKey(key) Removed, use SearchClient.delete_api_key instead delete_api_key(key, request_options=None)
delete_api_key(key, request_options=None) Removed, use SearchClient.delete_api_key instead delete_api_key(key, request_options=None)
delete_by(params, request_options=None) Changed delete_by(filters, request_options=None)
delete_by_query(query, params=None, request_options=None) Removed, use delete_by instead delete_by(filters, request_options=None)
delete_objects(objects, request_options=None) Changed delete_objects(object_ids, request_options=None)
delete_rule(objectID, forward_to_replicas=False, request_options=None) Changed delete_rule(object_id, request_options=None)
delete_synonym(object_id, forward_to_slaves=False, forward_to_replicas=False, request_options=None) Changed delete_synonym(object_id, request_options=None)
delete_user_key(key) Removed, use SearchClient.delete_api_key instead delete_api_key(key, request_options=None)
getObject(object_id, attributes_to_retrieve=None) Removed, use get_object instead get_object(object_id, request_options=None)
getObjects(object_ids) Removed, use get_objects instead get_objects(object_ids, request_options=None)
getSettings() Removed, use get_settings instead get_settings(request_options=None)
getUserKeyACL(key) Removed, use SearchClient.get_api_key instead get_api_key(key, request_options=None)
get_api_key_acl(key, request_options=None) Removed, use SearchClient.get_api_key instead get_api_key(key, request_options=None)
get_object(object_id, attributes_to_retrieve=None, request_options=None) Changed get_object(object_id, request_options=None)
get_objects(object_ids, attributes_to_retrieve=None, request_options=None) Changed get_objects(object_ids, request_options=None)
get_user_key_acl(key) Removed, use SearchClient.get_api_key instead get_api_key(key, request_options=None)
is_task_published(task_id, request_options=None) Removed  
iter_rules(hits_per_page=1000, request_options=None) Removed, use browse_rules instead browse_rules(request_options=None)
iter_synonyms(hits_per_page=1000, request_options=None) Removed, use browse_synonyms instead browse_synonyms(request_options=None)
listUserKeys() Removed, use SearchClient.list_api_keys instead list_api_keys(self, request_options=None)
list_api_keys(request_options=None) Removed, use SearchClient.list_api_keys instead list_api_keys(self, request_options=None)
list_user_keys() Removed, use SearchClient.list_api_keys instead list_api_keys(self, request_options=None)
partialUpdateObject(partial_object) Removed, use partial_update_object instead partial_update_object(obj, request_options=None)
partialUpdateObjects(objects) Removed, use partial_update_objects instead partial_update_objects(objects, request_options=None)
partial_update_object(partial_object, no_create=False, request_options=None) Changed partial_update_object(obj, request_options=None)
partial_update_objects(objects, no_create=False, request_options=None) Changed partial_update_objects(objects, request_options=None)
read_rule(objectID, request_options=None) Removed, use get_rule instead get_rule(object_id, request_options=None)
saveObject(obj) Removed, use save_object instead save_object(obj, request_options=None)
saveObjects(objects) Removed, use save_objects instead save_objects(objects, request_options=None)
save_rule(rule, forward_to_replicas=False, request_options=None) Changed save_rule(rule, request_options=None)
save_synonym(content, object_id, forward_to_slaves=False, forward_to_replicas=False, request_options=None) Changed save_synonym(synonym, request_options=None)
search(query, args=None, request_options=None) Changed search(query, request_options=None)
searchDisjunctiveFaceting(query, disjunctive_facets, params=None, refinements=None) Removed  
search_disjunctive_faceting(query, disjunctive_facets, params=None, refinements=None, request_options=None) Removed  
search_facet(facet_name, facet_query, query=None, request_options=None) Removed, use search_for_facet_values instead search_for_facet_values(facet_name, facet_query, request_options=None)
search_for_facet_values(facet_name, facet_query, query=None, request_options=None) Removed, use search_for_facet_values instead search_for_facet_values(facet_name, facet_query, request_options=None)
search_rules(query=None, anchoring=None, context=None, page=None, hitsPerPage=None, request_options=None) Changed search_rules(query, request_options=None)
search_synonyms(query, types=[], page=0, hits_per_page=100, request_options=None) Changed search_synonyms(query, request_options=None)
setSettings(settings) Removed, use set_settings instead set_settings(settings, request_options=None)
set_settings(settings, forward_to_slaves=True, forward_to_replicas=True, request_options=None) Changed set_settings(settings, request_options=None)
update_api_key(key, obj, validity=None, max_queries_per_ip_per_hour=None, max_hits_per_query=None, request_options=None) Removed, use SearchClient.update_api_key instead update_api_key(key, request_options=None)
update_user_key(key, obj, validity=None, max_queries_per_ip_per_hour=None, max_hits_per_query=None) Removed, use SearchClient.update_api_key instead update_api_key(key, request_options=None)
waitTask(task_id, time_before_retry=100) Removed, use wait_task instead wait_task(task_id, request_options=None)
wait_task(task_id, time_before_retry=100, request_options=None) Changed wait_task(task_id, request_options=None)

AnalyticsClient

You can initialize the AnalyticsClient as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- analytics = Client('app_id', 'api_key').init_analytics()

+ from algoliasearch.analytics_client import AnalyticsClient
+ analytics = AnalyticsClient.create('app_id', 'api_key')
List of method signature changes
1.20.0 Breaking Change 2.0.0
add_ab_test(ab_test) Changed add_ab_test(ab_test, request_options=None)
delete_ab_test(ab_test_id) Changed delete_ab_test(ab_test_id, request_options=None)
get_ab_test(ab_test_id) Changed get_ab_test(ab_test_id, request_options=None)
get_ab_tests(args=None) Changed get_ab_tests(request_options=None)
stop_ab_test(ab_test_id) Changed stop_ab_test(ab_test_id, request_options=None)
wait_task(index_name, task_id, time_before_retry=100, request_options=None) Removed  

InsightsClient

You can initialize the InsightsClient as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- insights = Client('app_id', 'api_key').init_insights()

+ from algoliasearch.insights_client import InsightsClient
+ insights = InsightsClient.create('app_id', 'api_key')
List of method signature changes
1.20.0 Breaking Change 2.0.0
post(data, request_options=None) Removed  

Using configuration

You can instantiate all clients with configuration objects. This is useful to change the way a client behaves.

All setters have been removed. If, for instance, you rely on set_extra_headers or set_timeout, you need to change your code to use a configuration object:

1
2
3
4
5
6
7
8
9
10
11
12
# v1
client.timeout = (1, 30)

# v2
from algoliasearch.configs import SearchConfig

config = SearchConfig()
config.read_timeout = 1
config.write_timeout = 30

client = SearchClient.create_with_config(config)

Optional methods parameters and requestOptions

To have the most consistent, predictable, and future-proof method signature, the API client follows three rules:

  • All required parameters have a single argument each
  • All optional arguments are passed in a request_options dictionary, as the last argument
  • The client never sets any default values

Here are some examples:

1
2
3
4
5
# v1
client.get_logs(0, 100, 'all')

# v2
client.get_logs({'offset': 0, 'length': 100, 'type': 'all'})
1
2
3
4
5
6
7
8
9
10
11
12
forward_to_replicas = True
synonym = {
  'objectID': 'a-unique-identifier',
  'type': 'altCorrection1',
  # ...
}

# v1
index.save_synonym(synonym, 'a-unique-identifier', forward_to_replicas)

# v2
index.save_synonym(synonym, {'forwardToReplicas': forward_to_replicas})
1
2
3
4
5
6
7
object = {'foo': 'bar'}

# v1
index.add_object(object)

# v2
index.save_object(object, {'autoGenerateObjectIDIfNotExist': True})
1
2
3
4
5
6
7
settings = {"searchableAttributes": ["name", "address"]}

# v1
index.set_settings(settings, True)

# v2
index.set_settings(settings, {'forwardToReplicas': True})

Exceptions

The import of the base AlgoliaException exception has changed:

1
2
3
4
5
# v1
from algoliasearch.helpers import AlgoliaException

# v2
from algoliasearch.exceptions import AlgoliaException
Did you find this page helpful?
Python API clients v3