Algolia Search API Client for .NET

Algolia Search is a hosted search engine capable of delivering realtime results from the first keystroke.

The Algolia Search API Client for .NET lets you easily use the Algolia Search REST API from your .NET code.

Contributing

Migration note from v5.x to v6.x

In January 2019, we released v6 of our .NET client. If you are using version 5.x of the client, read the migration guide to version 6.x. Version 5.x will no longer be under active development.

Note: If you're using ASP.NET, checkout the following tutorial.

API Documentation

You can find the full reference on Algolia's website.

1. Supported platforms

2. Install

3. Quick Start

4. Push data

5. Configure

6. Search

7. Search UI

8. List of available methods

9. Getting Help

10. List of available methods

Getting Started

Supported platforms

The API client follows .NET Standard thus it's compatible with:

• .NET Standard 1.3 to .NET Standard 2.0,
• .NET Core 1.0 to .NET Core 2.2,
• .NET Framework 4.5 to .NET Framework 4.7.1

Install

With the .NET CLI:

dotnet add package Algolia.Search

With the Nuget Package Manager Console:

Install-Package Algolia.Search

With Nuget.org

Download the package on Nuget.org.

POCO, Types and Json.NET

The API client is using Json.NET as serializer.

The Client is meant to be used with POCOs and Types to improve type safety and developer experience. You can directly index your POCOs if they follow the .NET naming convention for class and properties:

• PascalCase for property names
• PascalCase for class name

Example:

public class Contact
{
  public string ObjectID { get; set; }
  public string Name { get; set; }
  public int Age { get; set; }
}

SearchClient client = new SearchClient("YourApplicationID", "YourAdminAPIKey");
SearchIndex index = client.InitIndex("contact");

IEnumerable<Contact> contacts; // Fetch from DB or a Json file
index.SaveObjects(contacts);

// Retrieve one typed Contact
Contact contact = index.GetObject<Contact>("myId");

// Search one typed Contact
var result = index.Search<Contact>(new Query("contact"));

Note: If you can't follow the convention, you can still override the naming strategy with the following attribute [JsonProperty(PropertyName = "propertyName")]

However, it's still possible to use JObject to add and retrieve records.

    using (StreamReader re = File.OpenText("contacts.json"))
    using (JsonTextReader reader = new JsonTextReader(re))
    {
        JArray batch = JArray.Load(reader);
        index.SaveObjects(batch).Wait();
    }

    // Retrieve one JObject Contact
    JObject contact = index.GetObject<JObject>("myId");

Algolia objects such as Rule, Synonym, Settings, etc., are now typed. You can enjoy the completion of your favorite IDE while developing with the library.

Example with the Settings class:

IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string> {"attribute1", "attribute2"},
    AttributesForFaceting = new List<string> {"filterOnly(attribute2)"},
    UnretrievableAttributes = new List<string> {"attribute1", "attribute2"},
    AttributesToRetrieve = new List<string> {"attribute3", "attribute4"}
    // etc.
};

index.SetSettings(settings);

Asynchronous & Synchronous Methods

The API client provides both Async and Sync methods for every API endpoint. Asynchronous methods are suffixed with the Async keyword. You can use any of them depending on your needs.

// Synchronous
Contact res = index.GetObject<Contact>("myId");

// Asynchronous
Contact res = await index.GetObjectAsync<Contact>("myId");

HttpClient Injection

The API client is using the built-in HttpClient of the .NET Framework.

The HttpClient is wrapped in an interface: IHttpRequester. If you wish to use another HttpClient, you can inject it through the constructor while instantiating a SearchClient, AnalyticsClient, and InsightsClient.

Example:

IHttpRequester myCustomHttpClient = new MyCustomHttpClient();

SearchClient client = new SearchClient(
    new SearchConfig("YourApplicationId", "YourAdminAPIKey"),
    myCustomHttpClient
);

Multithreading

The client is designed to be thread-safe. You can use SearchClient, AnalyticsClient, and InsightsClient in a multithreaded environment.

Cross-Platform

As the API client is following .NET Standard, it can be used on Windows, Linux, or MacOS. The library is continuously tested in all three environments. If you want more information about .NET Standard, you can visit the official page.

Quick Start

In 30 seconds, this quick start tutorial will show you how to index and search objects.

Initialize the client

To start, you need to initialize the client. To do this, you need your Application ID and API Key. You can find both on your Algolia account.

SearchClient client = new SearchClient("YourApplicationID", "YourAdminAPIKey");
SearchIndex index = client.InitIndex("your_index_name");

Push data

Without any prior configuration, you can start indexing 500 contacts in the contacts index using the following code:

SearchIndex index = client.InitIndex("contacts");

using (StreamReader re = File.OpenText("contacts.json"))
using (JsonTextReader reader = new JsonTextReader(re))
{
    JArray batch = JArray.Load(reader);
    index.SaveObjects(batch, autoGenerateObjectId: true);
    // Asynchronous
    // index.SaveObjectsAsync(batch, autoGenerateObjectId: true);
}

Configure

You can customize settings to fine tune the search behavior. For example, you can add a custom ranking by number of followers to further enhance the built-in relevance:

IndexSettings settings = new IndexSettings
{
    CustomRanking = new List<string> { "desc(followers)"},
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

You can also configure the list of attributes you want to index by order of importance (most important first).

Note: Algolia is designed to suggest results as you type, which means you'll generally search by prefix. In this case, the order of attributes is crucial to decide which hit is the best.

IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string>
        {"lastname", "firstname", "company", "email", "city"}
};

// Synchronous
index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

Search

You can now search for contacts by firstname, lastname, company, etc. (even with typos):

// Search for a first name
index.Search<Contact>(new Query { "jimmie" });
// Asynchronous
await index.SearchAsync<Contact>(new Query { "jimmie" });

// Search for a first name with typo
index.Search<Contact>(new Query { "jimie" });
// Asynchronous
await index.SearchAsync<Contact>( new Query { "jimie" });

// Search for a company
index.Search<Contact>( new Query { "california paint" });
// Asynchronous
await index.SearchAsync<Contact>( new Query { "california paint" });

// Search for a first name and a company
index.Search<Contact>( new Query { "jimmie paint"" });
// Asynchronous
await index.SearchAsync<Contact>(new Query { "jimmie paint" });

Search UI

Warning: If you're building a web application, you may be interested in using one of our front-end search UI libraries.

The following example shows how to quickly build a front-end search using InstantSearch.js

index.html

<!doctype html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@7.1.1/themes/algolia.css" integrity="sha256-4SlodglhMbXjGQfNWiCBLSGNiq90FUw3Mtre9u4vLG8=" crossorigin="anonymous">
</head>
<body>
  <header>
    
  </header>

  <main>
      
      
  </main>

  <script type="text/html" id="hit-template">
    
      <p class="hit-name">
        {}{ "attribute": "firstname" }{{/helpers.highlight}}
        {}{ "attribute": "lastname" }{{/helpers.highlight}}
      </p>
    
  </script>

  <script src="https://cdn.jsdelivr.net/npm/algoliasearch@3.32.1/dist/algoliasearchLite.min.js" integrity="sha256-NSTRUP9bvh8kBKi7IHQSmOrMAdVEoSJFBbTA+LoRr3A=" crossorigin="anonymous"></script>
  <script src="https://cdn.jsdelivr.net/npm/instantsearch.js@3.2.0" integrity="sha256-/8usMtTwZ01jujD7KAZctG0UMk2S2NDNirGFVBbBZCM=" crossorigin="anonymous"></script>
  <script src="app.js"></script>
</body>

app.js

// Replace with your own values
const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey' // search only API key, not admin API key
);

const search = instantsearch({
  indexName: 'instant_search',
  searchClient,
  routing: true,
});

search.addWidget(
  instantsearch.widgets.configure({
    hitsPerPage: 10,
  })
);

search.addWidget(
  instantsearch.widgets.searchBox({
    container: '#search-box',
    placeholder: 'Search for products',
  })
);

search.addWidget(
  instantsearch.widgets.hits({
    container: '#hits',
    templates: {
      item: document.getElementById('hit-template').innerHTML,
      empty: `We didn't find any results for the search <em>"{{query}}"</em>`,
    },
  })
);

search.start();

List of available methods

Personalization

• Add strategy
• Get strategy

Search

• Search index
• Search for facet values
• Search multiple indices
• Browse index

Indexing

• Add objects
• Save objects
• Partial update objects
• Delete objects
• Replace all objects
• Delete by
• Clear objects
• Get objects
• Custom batch

Settings

• Get settings
• Set settings
• Copy settings

Manage indices

• List indices
• Delete index
• Copy index
• Move index

API keys

• Create secured API Key
• Add API Key
• Update API Key
• Delete API Key
• Restore API Key
• Get API Key permissions
• List API Keys

Synonyms

• Save synonym
• Batch synonyms
• Delete synonym
• Clear all synonyms
• Get synonym
• Search synonyms
• Replace all synonyms
• Copy synonyms
• Export Synonyms

Query rules

• Save rule
• Batch rules
• Get rule
• Delete rule
• Clear rules
• Search rules
• Replace all rules
• Copy rules
• Export rules

A/B Test

• Add A/B test
• Get A/B test
• List A/B tests
• Stop A/B test
• Delete A/B test

Insights

• Clicked Object IDs After Search
• Clicked Object IDs
• Clicked Filters
• Converted Objects IDs After Search
• Converted Object IDs
• Converted Filters
• Viewed Object IDs
• Viewed Filters

MultiClusters

• Assign or Move userID
• Get top userID
• Get userID
• List clusters
• List userIDs
• Remove userID
• Search userID

Advanced

• Get logs
• Configuring timeouts
• Set extra header
• Wait for operations

Vault

Getting Help

• Need help? Ask a question to the Algolia Community or on Stack Overflow.
• Found a bug? You can open a GitHub issue.