IndexDen API

The API defines methods to manage indexes (create and delete them), operate on them (add and delete documents, functions, etc), perform searches, etc.

All calls should be made to your specific private API url (which you'll find in your account's dashboard).

Every call will report its success via the HTTP status code returned. If the status code is 4xx or 5xx then the response body may contain a plain error message providing further details. If a 2xx code is returned the body will either be a JSON-serialized object or it'll be empty depending on the call.

Index Management

Before using an index you need to create an index and assign it a name. This name (NOT its code) has to be provided at creation time, and is used to reference that index in all other API calls.

HTTP Request / Description HTTP Response codes / body
GET /v1/indexes

Retrieves the metadata of every index in this account.

200 OK

The response body will contain a JSON map. Each key will be an index name, and its value, the index metadata. More details...

GET /v1/indexes/name

Retrieves metadata for the index name.

200 OK

The response body will contain a JSON map with metadata for the index. More details...

404 No index existed for the given name

The response body will be empty.

PUT /v1/indexes/name

Creates or updates an index with the given name. It cannot contain forward slashes "/".

The request body can contain a JSON object with:

  • "public_search": a boolean indicating whether public API is enable
201 An index has been created

The response body will contain a JSON map with metadata for the index. More details...

204 An index already existed for that name

If body was sent, the index will be modified according to the options sent. The response body will be empty.

409 Too many indexes for this account

A descriptive error message will be found in the body.

DELETE /v1/indexes/name

Removes the index name from the account.

200 OK

The response body will be empty.

204 No index existed for that name

The response body will be empty.

Indexing

Documents can be added, updated and deleted from the index. An identifier must be provided for each document. It can be your internal identifier for that document.

This identifier will be used in the search results to reference the matching documents. Every field defined in the indexed document will be searcheable. The indexed fields can be fetched or snippeted along with the search results.

HTTP Request / Description HTTP Response codes / body
PUT /v1/indexes/name/docs

Adds a document to the index name.

The request body should contain a JSON object with:

  • "docid": your document identifier A non-empty String no longer than 1024 bytes
  • "fields": a map from field name to field value. The sum of the length of each field value MUST not be greater than 100kbytes

And optionally:

  • "variables": a map from the var number to float
  • "categories": a map from the category name to its value
200 OK - Document indexed

The response body will be empty.

400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.

PUT /v1/indexes/name/docs

Adds a batch of documents to the index name.

The request body should contain a JSON list where each element should have the following attributes:

  • "docid": your document identifier A non-empty String no longer than 1024 bytes
  • "fields": a map from field name to field value. The sum of the length of each field value MUST not be greater than 100kbytes

And optionally:

  • "variables": a map from the var number to float
  • "categories": a map from the category name to its value
200 OK - Batch processed

The response body will be a JSON list where each element will have the following attributes:

  • "added": a boolean indicating whether the document in this position was successfully indexed
  • "error": a message detailing the reasons why a document was not successfully indexed
400 Invalid or missing argument

A descriptive error message will be found in the body. If any of the documents in the list was malformed, this response will be given and no document will be indexed.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.

DELETE /v1/indexes/name/docs

Removes a document from the index name.

The request body should contain a JSON object with:

  • "docid": the document identifier

For clients that do not support body in DELETE requests the docid can be sent in the querystring

200 OK - Document deleted

The response body will be empty.

400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.

DELETE /v1/indexes/name/docs

Removes a bulk of documents from the index name.

The request body should contain a JSON List where each element should have the following attributes:

  • "docid": the document identifier

For clients that do not support body in DELETE requests the docid can be sent in the querystring

200 OK - Bulk delete processed

The response body will be a JSON list where each element will have the following attributes:

  • "deleted": a boolean indicating whether the document in this position was successfully deleted
  • "error": a message detailing the reasons why a document was not successfully deleted
400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.

Scoring variables

Documents can have numeric variables attached to them. These variables can be used in scoring functions for sorting search results. Variables can be updated rapidly; these updates don't count towards your indexing limits.

HTTP Request / Description HTTP Response codes / body
PUT /v1/indexes/name/docs/variables

Update the variables of a document in index name.

The request body should contain a JSON object with:

  • "docid": your document identifier
  • "variables": a map from the var number to float
200 OK - Variables indexed

The response body will be empty.

400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.

Categories

Documents already added can be categorized. Categories are a way to partition your index for different dimensions. For instance, you may want to have your documents grouped by type (cds, books), price range (0-99, 100-199), manufacturer, author, or any dimension in which your documents have meaning. For every category (the dimension) every document can have multiple values.

These categories can be used later to filter your query (e.g.: only return books that cost between 0 and 100 dollars) or to facet the results of a query (i.e. showing the user how many documents, for each category and category value, match the query)

HTTP Request / Description HTTP Response codes / body
PUT /v1/indexes/name/docs/categories

Update the categories of a document in index name.

The request body should contain a JSON object with:

  • "docid": your document identifier
  • "categories": a map from the categories' names to the values for this document
200 OK - Categories indexed

The response body will be empty.

400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.

Scoring functions

Scoring functions can be defined through the API. These functions can later be used when searching the index to provide specific orderings for the results. They can use the variables defined in the document as well as some special variables such as the document's age and the textual relevance of the match. You can find more detail in the function definition syntax page.

Geolocation can be used to prioritize documents closer to (or further from) the user's location. Check the distance functions for this.

HTTP Request / Description HTTP Response codes / body
GET /v1/indexes/name/functions

Retrieves all the functions defined for the index name.

200 OK

The response body will contain a JSON map from the function number to its definition.

404 No index existed for the given name

The response body will be empty.

409 The index was initializing

This will happen until the value for "started" in the metadata is true.

PUT /v1/indexes/name/functions/num

Defines the function number num for the index name.

The request body should contain a JSON object with:

  • "definition":the formula that defines the function
200 OK - Function saved

The response body will be empty.

400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

The response body will be empty.

409 The index was initializing

This will happen until the value for "started" in the metadata is true.

DELETE /v1/indexes/name/functions/num

Removes the function num from the index name.

200 OK - Function deleted

The response body will be empty.

400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

The response body will be empty.

409 The index was initializing

This will happen until the value for "started" in the metadata is true.

503 Service Unavailable

A descriptive error message will be found in the body.

Searching

A query must be provided to search an index. Optional parameters include: start and length (for results paging), a scoring function (for results ordering), and a list of fetch and snippet fields (for getting stored data).

Search results will contain the document identifiers provided at indexing time. If fetch and snippet fields were specified, the field's content or a snippet of the content can be returned along with the identifiers.

HTTP Request / Description HTTP Response codes / body
GET /v1/indexes/name/search

Performs a search on the index name.

The query string should contain:

  • "q":the query to be performed

And optionally:

  • "start": for paging, the first position to return
  • "len": how many results to return (default: 10)
  • "function": the number of the scoring function to use (default: 0)
  • "fetch": comma-separated list of fields to fetch. '*' returns all present fields for each document
  • "fetch_variables": 'true' returns all variables for each document as variable_<N> (unset vars return 0)
  • "fetch_categories": 'true' returns all categories for each document as category_<NAME>
  • "snippet": comma-separated list of fields to snippet
  • "var<N>": value of the query variable <N>
  • "category_filters": a json map from category name to a list of the admitted values for those categories
  • "filter_docvar<N>":comma-separated list of ranges to filter the values of variable <N>. Each range is expressed as BOTTOM:TOP, where any of both limits can be replaced by an * symbol to indicate it should be ignored
  • "filter_function<N>":comma-separated list of ranges to filter the values of function <N>. Each range is expressed as BOTTOM:TOP, where any of both limits can be replaced by an * symbol to indicate it should be ignored
  • "match_any_field": 'true' - global search inside whole index (default false)
200 OK

The response body will contain a JSON map with these fields:

  • "matches": the total number of matches for the query
  • "facets": a map from category name to a values count map
  • "results": a list of objects with the "docid" field
    • "query_relevance_score": query specific document relevance score
    • "variable_<N>": variable value, from 0 to N
    • "category_<NAME>": category value for the NAME document category / facet
  • "search_time":the time it took to search in seconds
400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.

DELETE /v1/indexes/name/search

Performs a search on the index name.

The query string should contain:

  • "q":the query to be performed

And optionally:

  • "start": for paging, the first position to return
  • "function": the number of the scoring function to use (default: 0)
  • "var<N>": value of the query variable <N>
  • "category_filters": a json map from category name to a list of the admitted values for those categories
  • "filter_docvar<N>":comma-separated list of ranges to filter the values of variable <N>. Each range is expressed as BOTTOM:TOP, where any of both limits can be replaced by an * symbol to indicate it should be ignored
  • "filter_function<N>":comma-separated list of ranges to filter the values of function <N>. Each range is expressed as BOTTOM:TOP, where any of both limits can be replaced by an * symbol to indicate it should be ignored
200 OK

The response body will be empty.

400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.

Promoting results

The API also allows you to promote a document to the top of a query's result page

HTTP Request / Description HTTP Response codes / body
PUT /v1/indexes/name/promote

Promotes a document for a query on the index name.

The request body should contain a JSON object with:

  • "docid":the id of the document to promote
  • "query":the query to in which to promote it
200 OK - The document has been promoted

The response body will be empty.

400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.

Index metadata

Some methods will return metadata for an index. This metadata will be in the form of a JSON object and will include the following fields:

Field name Content
started boolean true / false

A boolean value representing whether the given index has started.

False usually means that the index has been recently created and isn't available yet.

code string alphanumeric

A string with an alphanumeric code that uniquely identifies the index under the given name.

If an index is deleted and a new one is created with the same name, it will have a different code.

creation_time string ISO 8601 formatted date

A string with the time when this index was created formatted according to the ISO 8601 format.

For example: 2010-01-01T12:00:00

updated_time string ISO 8601 formatted date

A string with the time when this index was modified last time - formatted according to the ISO 8601 format.

For example: 2010-01-01T12:00:00

size integer

An integer with the size in documents of this index. The size is not updated in real-time so the value may be up to a minute old.

public_search boolean true / false

A boolean value indicating whether public search API is enabled.

Autocomplete

JSON data source to work with Indextank-jQuery Autocomplete.

Additional support for JSONP is provided.

HTTP Request / Description HTTP Response codes / body
GET /v1/indexes/name/autocomplete

Performs a search on the index name.

The querystring parameters should contain:

  • "query":the query to be performed

And optionally:

  • "field":the field to take suggestions from. By default, 'text' field will be chosen.
  • "callback":the callback JS function on the client (enables JSONP), if callback is present response will be JSONP, if no callback is present, response will be a JSON map
200 OK

The response body will be JSONP or a JSON map with these fields:

  • "suggestions":JSON array with query matches
  • "query":requested query parameter (may be normalized)
400 Invalid or missing argument

A descriptive error message will be found in the body.

404 No index existed for the given name

A descriptive error message will be found in the body.

409 The index was initializing

Until the value for "started" in the metadata is true attempts to add a document will fail.

503 Service Unavailable

A descriptive error message will be found in the body.


Real Time Web Analytics