{"id":2379,"library":"algoliasearch","title":"Algolia Python API Client","description":"The `algoliasearch` library is a fully-featured and blazing-fast Python API client designed to interact with the Algolia Search API. It provides a Pythonic interface to index data, configure search settings, perform queries, and access advanced features like analytics and recommendations. The library is actively maintained with frequent minor releases, currently at version 4.38.0.","status":"active","version":"4.38.0","language":"en","source_language":"en","source_url":"https://github.com/algolia/algoliasearch-client-python","tags":["search","api-client","algolia","full-text-search"],"install":[{"cmd":"pip install --upgrade 'algoliasearch>=4.0,<5.0'","lang":"bash","label":"Install latest v4"}],"dependencies":[{"reason":"Requires Python 3.8.1 or newer.","package":"Python","optional":false}],"imports":[{"note":"The `algoliasearch.Client` and direct `algoliasearch` module import patterns were used in older major versions (v1/v2). For v3 and v4, `SearchClient` from `algoliasearch.search.client` is the correct entry point.","wrong":"from algoliasearch import algoliasearch","symbol":"SearchClient","correct":"from algoliasearch.search.client import SearchClient"}],"quickstart":{"code":"import os\nfrom algoliasearch.search.client import SearchClient\n\n# Initialize the client with your Application ID and API Key\n# Ensure you use your Admin API Key for indexing operations, and Search-Only API Key for search.\nAPP_ID = os.environ.get('ALGOLIA_APP_ID', 'YOUR_ALGOLIA_APP_ID')\nAPI_KEY = os.environ.get('ALGOLIA_API_KEY', 'YOUR_ALGOLIA_ADMIN_API_KEY') # Use Admin API Key for writes\nINDEX_NAME = os.environ.get('ALGOLIA_INDEX_NAME', 'your_index_name')\n\nif not APP_ID or not API_KEY:\n    print(\"Please set ALGOLIA_APP_ID and ALGOLIA_API_KEY environment variables or replace placeholders.\")\nelse:\n    try:\n        client = SearchClient.create(APP_ID, API_KEY)\n        index = client.init_index(INDEX_NAME)\n\n        # Add a new record\n        record = {\"objectID\": \"1\", \"name\": \"Algolia Search\", \"category\": \"Search Engines\"}\n        save_response = index.save_object(record).wait()\n        print(f\"Object saved: {save_response.object_ids[0]}\")\n\n        # Search for records\n        search_results = index.search('Algolia', {\n            'attributesToRetrieve': ['name', 'category'],\n            'hitsPerPage': 1\n        })\n        \n        print(\"\\nSearch Results:\")\n        for hit in search_results['hits']:\n            print(f\"- Name: {hit['name']}, Category: {hit['category']}\")\n\n        # Update an existing record\n        index.partial_update_object({\"objectID\": \"1\", \"description\": \"Fast and relevant search.\"}).wait()\n        print(\"\\nObject updated.\")\n\n        # Delete a record (optional, uncomment to run)\n        # index.delete_object(\"1\").wait()\n        # print(\"\\nObject deleted.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the Algolia client, initialize an index, add a new object, search for objects, and update an object. Remember to replace placeholder API keys and application IDs with your actual credentials, ideally fetched from environment variables. For indexing operations, always use your Admin API Key."},"warnings":[{"fix":"Review the official upgrade guide for Python API Client v4. Update client initialization and method calls according to the new `SearchClient` patterns and `request_options` usage.","message":"Major breaking changes occurred when upgrading from `algoliasearch` v3 to v4. The client initialization method changed significantly from `algoliasearch.client.Client` to `algoliasearch.search.client.SearchClient.create`. Many method signatures were also updated to accept optional arguments via a `request_options` dictionary, instead of individual parameters.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always check the release notes and changelog for each minor version update, especially for mentions of 'BREAKING CHANGES' related to API schema or model updates. Adapt your code to the updated data structures or API parameter requirements.","message":"Breaking changes related to API schema fixes are introduced in minor versions. For instance, v4.36.0 included changes to `conditions` in composition rules, and v4.35.3 removed field requirements from the Composition API's run response. These can impact client types and expected data structures.","severity":"breaking","affected_versions":">=4.35.3, >=4.36.0"},{"fix":"Ensure you are using your Algolia Admin API Key (not the Search-Only API Key) when performing operations like `save_object`, `delete_object`, or modifying index settings. The Search-Only API Key should only be used for read operations (e.g., `search`).","message":"Using the Search-Only API Key for indexing or administrative operations will result in permission errors. These operations require an Admin API Key.","severity":"gotcha","affected_versions":"All v4 versions"},{"fix":"Configure connection timeouts for the Algolia client. You can create a `SearchConfig` object and pass it to `SearchClient.create_with_config()` to set `connect_timeout`, `read_timeout`, and `write_timeout` to appropriate values for your network environment. Consult your network administrator for allowed outbound connections.","message":"Users behind corporate firewalls or with strict network configurations might encounter 'Unreachable hosts' errors. This usually indicates a timeout or connection issue preventing the client from reaching Algolia's servers.","severity":"gotcha","affected_versions":"All v4 versions"},{"fix":"If experiencing `urllib3` dependency conflicts, consider pinning `algoliasearch` to a version immediately prior to 4.31.0 (e.g., `algoliasearch==4.30.0`) or explicitly pinning `urllib3` to a compatible version if other libraries permit it. Check your `pip freeze` output for `urllib3` conflicts.","message":"Version 4.31.0 introduced a potentially breaking `urllib3` dependency constraint that could conflict with other packages in your environment.","severity":"gotcha","affected_versions":"4.31.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}