Csharp

Advanced

Custom batch - Batch

You may want to perform multiple operations with one API call to reduce latency.

If you have one index per user, you may want to perform a batch operations across several indices. We expose a method to perform this type of batch:

List<JObject> objs = new List<JObject>();
objs.Add(JObject.Parse(@"{""action"":""addObject"", ""indexName"": ""index1"", ""body"": {""firstname"":""Roger"", ""lastname"":""Barninger""}}"));
objs.Add(JObject.Parse(@"{""action"":""addObject"", ""indexName"": ""index2"", ""body"": {""firstname"":""Roger"", ""lastname"":""Speach""}}"));
client.Batch(objs);

The attribute action can have these values:

  • addObject
  • updateObject
  • partialUpdateObject
  • partialUpdateObjectNoCreate
  • deleteObject

Backup / Export an index - Browse

The search method cannot return more than 1,000 results. If you need to retrieve all the content of your index (for backup, SEO purposes or for running a script on it), you should use the browse method instead. This method lets you retrieve objects beyond the 1,000 limit.

This method is optimized for speed. To make it fast, distinct, typo-tolerance, word proximity, geo distance and number of matched words are disabled. Results are still returned ranked by attributes and custom ranking.

Response Format

Sample
{
  "hits": [
    {
      "firstname": "Jimmie",
      "lastname": "Barninger",
      "objectID": "433"
    }
  ],
  "processingTimeMS": 7,
  "query": "",
  "params": "filters=level%3D20",
  "cursor": "ARJmaWx0ZXJzPWxldmVsJTNEMjABARoGODA4OTIzvwgAgICAgICAgICAAQ=="
}
Fields
  • cursor (string, optional): A cursor to retrieve the next chunk of data. If absent, it means that the end of the index has been reached.
  • query (string): Query text used to filter the results.
  • params (string, URL-encoded): Search parameters used to filter the results.
  • processingTimeMS (integer): Time that the server took to process the request, in milliseconds. Note: This does not include network time.

The following fields are provided for convenience purposes, and only when the browse is not filtered:

  • nbHits (integer): Number of objects in the index.
  • page (integer): Index of the current page (zero-based).
  • hitsPerPage (integer): Maximum number of hits returned per page.
  • nbPages (integer): Number of pages corresponding to the number of hits. Basically, ceil(nbHits / hitsPerPage).

Example

// Iterate with a filter over the index
IndexIterator it = index.BrowseAll(new Query("text"));

// Retrieve the next cursor from the browse method
System.Diagnostics.Debug.WriteLine(index.BrowseFrom(new Query("text"), null)["cursor"]);

List api keys - ListApiKeys

To list existing keys, you can use:

// Lists global API Keys
var keys = client.ListUserKeys();
// Asynchronous
// var keys = await client.ListUserKeysAsync();
// Lists API Keys that can access only to this index
keys = index.ListUserKeys();
// Asynchronous
// keys = await index.ListUserKeysAsync();

Each key is defined by a set of permissions that specify the authorized actions. The different permissions are:

  • search: Allowed to search.
  • browse: Allowed to retrieve all index contents via the browse API.
  • addObject: Allowed to add/update an object in the index.
  • deleteObject: Allowed to delete an existing object.
  • deleteIndex: Allowed to delete index content.
  • settings: allows to get index settings.
  • editSettings: Allowed to change index settings.
  • analytics: Allowed to retrieve analytics through the analytics API.
  • listIndexes: Allowed to list all accessible indexes.

Add user key - AddUserKey

To create API keys:

// Creates a new global API key that can only perform search actions
var res = client.AddUserKey(new String[] { "search" });
// Asynchronous
// var res = await client.AddUserKeyAsync(new String[] { "search" });
System.Diagnostics.Debug.WriteLine("Key: " + res["key"]);
// Creates a new API key that can only perform search action on this index
res = index.AddUserKey(new String[] { "search" });
// Asynchronous
// res = await index.AddUserKeyAsync(new String[] { "search" });
System.Diagnostics.Debug.WriteLine("Key: " + res["key"]);

You can also create an API Key with advanced settings:

validity

Add a validity period. The key will be valid for a specific period of time (in seconds).

maxQueriesPerIPPerHour

Specify the maximum number of API calls allowed from an IP address per hour. Each time an API call is performed with this key, a check is performed. If the IP at the source of the call did more than this number of calls in the last hour, a 403 code is returned. Defaults to 0 (no rate limit). This parameter can be used to protect you from attempts at retrieving your entire index contents by massively querying the index.

maxHitsPerQuery

Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire index contents by massively querying the index.

indexes

Specify the list of targeted indices. You can target all indices starting with a prefix or ending with a suffix using the ‘*’ character. For example, “dev_*” matches all indices starting with “dev_” and “*_dev” matches all indices ending with “_dev”. Defaults to all indices if empty or blank.

referers

Specify the list of referers. You can target all referers starting with a prefix, ending with a suffix using the ‘*’ character. For example, “https://algolia.com/*” matches all referers starting with “https://algolia.com/” and “*.algolia.com” matches all referers ending with “.algolia.com”. If you want to allow the domain algolia.com you can use “*algolia.com/*”. Defaults to all referers if empty or blank.

queryParameters

Specify the list of query parameters. You can force the query parameters for a query using the url string format (param1=X&param2=Y…).

description

Specify a description to describe where the key is used.

// Creates a new index specific API key valid for 300 seconds, with a rate limit of 100 calls per hour per IP and a maximum of 20 hits

Dictionary<string, object> param = new Dictionary<string, object>();
param["acl"] = new String[] { "search" };
param["validity"] = 300;
param["maxQueriesPerIPPerHour"] = 100;
param["maxHitsPerQuery"] = 20;
param["indexes"] = new string[]{"dev_*"};
param["referers"] = new string[]{"algolia.com/*"};
param["queryParameters"] = "typoTolerance=strict&ignorePlurals=false";
param["description"] = "Limited search only API key for algolia.com";

res = index.AddUserKey(param);
// Asynchronous
// res = await index.AddUserKeyAsync(param);
System.Diagnostics.Debug.WriteLine("Key: " + res["key"]);

Update user key - UpdateUserKey

To update the permissions of an existing key:

// Update an existing global API key that is valid for 300 seconds
var res = client.UpdateUserKey("myAPIKey", new String[] { "search" }, 300, 0, 0, new string[]{"dev_*"});
// Asynchronous
// var res = await client.UpdateUserKeyAsync("myAPIKey", new String[] { "search" }, 300, 0, 0, new string[]{"dev_*"});
System.Diagnostics.Debug.WriteLine("Key: " + res["key"]);
// Update an existing index specific API key valid for 300 seconds, with a rate limit of 100 calls per hour per IP and a maximum of 20 hits
res = index.UpdateUserKey("myAPIKey", new String[] { "search" }, 300, 100, 20, new string[]{"dev_*"});
// Asynchronous
// res = await index.UpdateUserKeyAsync("myAPIKey", new String[] { "search" }, 300, 100, 20, new string[]{"dev_*"});
System.Diagnostics.Debug.WriteLine("Key: " + res["key"]);

To get the permissions of a given key:

// Gets the rights of a global key
var res = client.GetUserKeyACL("f420238212c54dcfad07ea0aa6d5c45f");
// Asynchronous
// var res = await client.GetUserKeyACLAsync("f420238212c54dcfad07ea0aa6d5c45f");

// Gets the rights of an index specific key
res = index.GetUserKeyACL("71671c38001bf3ac857bc82052485107");
// Asynchronous
// res = await index.GetUserKeyACLAsync("71671c38001bf3ac857bc82052485107");

Delete user key - DeleteUserKey

To delete an existing key:

// Deletes a global key
client.DeleteUserKey("f420238212c54dcfad07ea0aa6d5c45f");
// Asynchronous
// await client.DeleteUserKeyAsync("f420238212c54dcfad07ea0aa6d5c45f");
// Deletes an index specific key
  index.DeleteUserKey("71671c38001bf3ac857bc82052485107");
// Asynchronous
// await index.DeleteUserKeyAsync("71671c38001bf3ac857bc82052485107");

Get key permissions - GetUserKeyACL

To get the permissions of a given key:

// Gets the rights of a global key
var res = client.GetUserKeyACL("f420238212c54dcfad07ea0aa6d5c45f");
// Asynchronous
// var res = await client.GetUserKeyACLAsync("f420238212c54dcfad07ea0aa6d5c45f");

// Gets the rights of an index specific key
res = index.GetUserKeyACL("71671c38001bf3ac857bc82052485107");
// Asynchronous
// res = await index.GetUserKeyACLAsync("71671c38001bf3ac857bc82052485107");

Get latest logs - GetLogs

You can retrieve the latest logs via this API. Each log entry contains:

  • Timestamp in ISO-8601 format
  • Client IP
  • Request Headers (API Key is obfuscated)
  • Request URL
  • Request method
  • Request body
  • Answer HTTP code
  • Answer body
  • SHA1 ID of entry

You can retrieve the logs of your last 1,000 API calls and browse them using the offset/length parameters:

offset

Specify the first entry to retrieve (0-based, 0 is the most recent log entry). Defaults to 0.

length

Specify the maximum number of entries to retrieve starting at the offset. Defaults to 10. Maximum allowed value: 1,000.

onlyErrors

Retrieve only logs with an HTTP code different than 200 or 201. (deprecated)

type

Specify the type of logs to retrieve:

  • query: Retrieve only the queries.
  • build: Retrieve only the build operations.
  • error: Retrieve only the errors (same as onlyErrors parameters).
// Get last 10 log entries
client.GetLogs();
// Asynchronous
// await client.GetLogsAsync();
// Get last 100 log entries
client.GetLogs(0, 100);
// Asynchronous
// await client.GetLogsAsync(0, 100);

REST API

We’ve developed API clients for the most common programming languages and platforms. These clients are advanced wrappers on top of our REST API itself and have been made in order to help you integrating the service within your apps: for both indexing and search.

Everything that can be done using the REST API can be done using those clients.

The REST API lets your interact directly with Algolia platforms from anything that can send an HTTP request Go to the REST API doc