SDKs overview

Typesense offers a range of official Software Development Kits (SDKs) and client libraries designed to facilitate interaction with its search engine API. These SDKs abstract the underlying HTTP API calls, simplifying common operations such as indexing documents, performing search queries, and managing collections. By providing idiomatic interfaces for various programming languages, Typesense aims to reduce the development effort required for integrating fast, typo-tolerant search capabilities into web, mobile, and backend applications. Each SDK is maintained to align with the latest Typesense API specifications, ensuring compatibility and access to new features. Developers can consult the official Typesense API reference documentation for comprehensive details on available endpoints and data structures.

The client libraries handle critical aspects such as connection management, request serialization (converting native data structures to JSON), response deserialization, and error handling. This abstraction allows developers to focus on application logic rather than low-level networking concerns. For instance, when performing a search, the SDK constructs the appropriate query parameters, signs the request securely, and parses the JSON response into a language-native object or data structure. This approach is consistent with best practices for API client development, as outlined in general API client library guidelines, which emphasize ease of use and reduced boilerplate code.

Official SDKs by language

Typesense provides official client libraries for several popular programming languages, ensuring broad compatibility for various development environments. These libraries are typically open-source and available through standard package managers for each respective language.

Language Package Name Maturity Documentation Link
JavaScript typesense-js Stable Typesense JavaScript client documentation
PHP typesense/typesense-php Stable Typesense PHP client documentation
Python typesense Stable Typesense Python client documentation
Ruby typesense Stable Typesense Ruby client documentation
Go github.com/typesense/typesense-go Stable Typesense Go client documentation
Dart typesense Stable Typesense Dart client documentation
Java org.typesense:typesense-java Stable Typesense Java client documentation

Installation

Installing Typesense SDKs is typically straightforward, using the standard package manager for each respective language. Below are common installation commands:

JavaScript (Node.js & Browsers)

npm install typesense
# or
yarn add typesense

The JavaScript client supports both Node.js environments and modern web browsers. When used in a browser, it's common to configure a search-only API key for security reasons, limiting its permissions to read-only operations. This prevents unauthorized data modification or deletion from client-side code.

PHP

composer require typesense/typesense-php

The PHP client is designed for server-side applications and integrates well with frameworks like Laravel or Symfony. It requires PHP versions 7.4 or newer, consistent with modern PHP application development practices.

Python

pip install typesense

The Python client is suitable for backend services, data indexing scripts, and command-line tools. It supports Python 3.6+ and provides a synchronous interface, which is often preferred for server-side operations.

Ruby

gem install typesense

The Ruby client is distributed as a Gem and can be integrated into Ruby on Rails applications or other Ruby projects by adding it to the Gemfile. It provides an idiomatic Ruby interface for interacting with the Typesense API.

Go

go get github.com/typesense/typesense-go/typesense

The Go client is designed for high-performance server applications. Its API mirrors the structure of the Typesense REST API, making it familiar to developers who have worked with the HTTP endpoints directly. Go's concurrency model can be utilized for efficient indexing and searching operations.

Dart

dart pub add typesense

The Dart client is suitable for Flutter mobile and web applications, as well as server-side Dart applications. It provides a reactive interface, often using Futures, which aligns with Dart's asynchronous programming model.

Java

For Java projects, you would typically add the Typesense Java client as a dependency in your build tool, such as Maven or Gradle.

Maven

<dependency>
    <groupId>org.typesense</groupId>
    <artifactId>typesense-java</artifactId>
    <version>YOUR_TYPESENSE_JAVA_VERSION</version>
</dependency>

Gradle

implementation 'org.typesense:typesense-java:YOUR_TYPESENSE_JAVA_VERSION'

The Java client is designed for enterprise-grade applications and integrates with the Java ecosystem. It provides a robust, type-safe way to interact with the Typesense API, supporting various data types and complex query structures.

Quickstart example

This Python example illustrates how to initialize the Typesense client, create a collection, index a document, and perform a basic search query. This process demonstrates the fundamental steps involved in setting up and interacting with Typesense using an SDK.

import typesense

# 1. Initialize the client
client = typesense.Client({
    'nodes': [{
        'host': 'localhost',  # or your Typesense Cloud host
        'port': '8108',       # or 443 for HTTPS
        'protocol': 'http'    # or 'https'
    }],
    'api_key': 'xyz', # Replace with your Typesense API key
    'connection_timeout_seconds': 2
})

# 2. Define a collection schema
schema = {
    'name': 'books',
    'fields': [
        {'name': 'title', 'type': 'string'},
        {'name': 'author', 'type': 'string'},
        {'name': 'publication_year', 'type': 'int32'},
        {'name': 'ratings_count', 'type': 'int32', 'facet': True},
        {'name': 'average_rating', 'type': 'float'}
    ],
    'default_sorting_field': 'average_rating'
}

# 3. Create the collection
try:
    client.collections.create(schema)
    print("Collection 'books' created successfully.")
except typesense.exceptions.ObjectAlreadyExists: # Handle if collection already exists
    print("Collection 'books' already exists.")

# 4. Index a document
document = {
    'id': '1',
    'title': 'The Hitchhiker\'s Guide to the Galaxy',
    'author': 'Douglas Adams',
    'publication_year': 1979,
    'ratings_count': 10000,
    'average_rating': 4.2
}

client.collections['books'].documents.create(document)
print("Document indexed successfully.")

# 5. Perform a search query
search_parameters = {
    'q': 'hitchhiker',
    'query_by': 'title',
    'sort_by': 'publication_year:desc'
}

search_results = client.collections['books'].documents.search(search_parameters)
print("Search Results:", search_results)

# Example of deleting a collection (optional)
# client.collections['books'].delete()
# print("Collection 'books' deleted.")

This example demonstrates a full lifecycle: defining a data structure, creating it on the Typesense server, adding data, and retrieving it through a search. The api_key used here must be a valid API key with appropriate permissions (e.g., admin permissions for creating collections and indexing, search-only for search queries). For production environments, it is crucial to manage API keys securely, often using environment variables or secret management systems rather than hardcoding them.

Community libraries

Beyond the official SDKs, the Typesense ecosystem includes various community-contributed libraries and integrations that extend its functionality or provide wrappers for specific frameworks. These often address niche use cases or offer alternative approaches to integration.

  • Typesense WordPress Plugin: Integrates Typesense search into WordPress sites, replacing the default search functionality with a faster, more relevant experience. This plugin handles data synchronization and search UI integration.
  • Typesense Laravel Scout Driver: Provides a Typesense driver for Laravel Scout, allowing Laravel developers to use Typesense as their search backend with minimal code changes, leveraging Laravel's existing search syntax.
  • Typesense-InstantSearch.js Adapter: An adapter that allows Typesense to be used with InstantSearch.js, a popular UI library for building rich, real-time search experiences. This enables developers to create sophisticated search interfaces with features like faceting, pagination, and sorting, while powered by Typesense.
  • Go-Typesense-CLI: A command-line interface tool written in Go that provides a convenient way to interact with Typesense from the terminal, useful for administrative tasks, data import/export, and debugging.
  • Typesense Elixir Client: While not officially maintained, community efforts have produced an Elixir client, allowing integration with Elixir/Phoenix applications. These community-driven projects can be found on platforms like GitHub and are often maintained by enthusiastic members of the Typesense user base.

It is advisable to check the specific documentation or GitHub repositories for community libraries to understand their current maintenance status, compatibility with the latest Typesense versions, and community support levels. While not officially supported, these libraries can offer valuable integrations for specific technology stacks.