Initialize the .NET API client

Before you can interact with Algolia’s APIs, for example, to index your data or search your indices, you need to authenticate with Algolia with your Application ID and API key by initializing a client. You can find both in your Algolia account.

Initialize the search client

The search client lets you manage your indices, add data to your indices, and search your indices.

1
2
SearchClient client = new SearchClient("YourApplicationID", "YourWriteAPIKey");
SearchIndex index = client.InitIndex("your_index_name");

Replace your_index_name with the name of the index you want to use. You can find your existing indices in the Algolia dashboard, or by using the listIndices method. If the index doesn’t exist, a new, empty index is created locally. It’s created on Algolia’s servers only if you add records to the index.

Don’t use any sensitive or personally identifiable information as your index name, including usernames, IDs, or email addresses. Index names are publicly shared.

Operations, that are scoped to your Algolia application via the client are:

• Manage indices
• Manage dictionaries
• Manage API keys

Operations scoped to an index are:

• Search
• Indexing
• Set and get settings
• Define synonyms
• Define Rules

The Recommend, Personalization, Insights, and A/B testing APIs come with their own clients.

Usage notes

Serialization

The API client is using Json.NET as serializer for your POCOs.

You can index your POCOs directly, if they follow the .NET naming convention.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public class Contact
{
  public string ObjectID { get; set; }
  public string Name { get; set; }
  public int Age { get; set; }
}

SearchClient client = new SearchClient("YourApplicationID", "YourWriteAPIKey");
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"));

You can override the naming strategy with the following attribute: [JsonProperty(PropertyName = "propertyName")]

You can also add and retrieve records via JObject:

1
2
3
4
5
6
7
8
9
    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, or Settings, are now typed.

Example with the Settings class:

1
2
3
4
5
6
7
8
9
10
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);

If you want to access all properties of the SearchResponse object, you must add these properties to your class. For example, to get the _rankingInfo attribute with your search:

1
2
3
4
5
6
7
8
public class Contact
{
  public string ObjectID { get; set; }
  public string Name { get; set; }
  public int Age { get; set; }

  public object _rankingInfo { get; set; }
}

Asynchronous and synchronous methods

The API client provides both synchronous and asynchronous methods for every API endpoint. Asynchronous methods are suffixed with the Async keyword.

1
2
3
4
5
// Synchronous
Contact res = index.GetObject<Contact>("myId");

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

Using a custom HTTP client

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

The HttpClient is wrapped in an interface: IHttpRequester. If you want to use a custom HttpClient, you can pass it to the constructors of If you wish to use another HttpClient, you can inject it through the constructor when instantiating a SearchClient, AnalyticsClient, or InsightsClient.

Example:

1
2
3
4
5
6
IHttpRequester myCustomHttpClient = new MyCustomHttpClient();

SearchClient client = new SearchClient(
    new SearchConfig("YourApplicationID", "YourWriteAPIKey"),
    myCustomHttpClient
);

Thread safety

The API client is thread-safe. You can use SearchClient, AnalyticsClient, and InsightsClient in a multi-threaded environment.