# Neuralens Docs

## Welcome to Neuralens

Here you'll find all the resources you need to get up and running with Neuralens AI Search.

## Want to jump right in?

Feeling like an eager beaver? Jump in to the quick start docs and get making your first request:

{% content-ref url="/pages/LkWTKY4tjpWMUBfbiNLG" %}
[Quick Start](/quick-start)
{% endcontent-ref %}

## Want to deep dive?

Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:

{% content-ref url="/pages/lKjJDNizpHxOGtMgoHcD" %}
[API Reference](/reference/api-reference)
{% endcontent-ref %}


# Quick Start

{% hint style="info" %}
**Two APIs to go live:** This quick start guide will take you through the two APIs required for you to go live with Neuralens AI search: Indexing, and Search.
{% endhint %}

## Get your API keys

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.

## Indexing API

Indexing is how you add your products to the search engine. For better understanding by the Neuralens Engine and better relevance, refer the set of [standardized fields](/reference/api-reference/indexing#standardized-fields). If you product attributes are not in the standardized set, you can use [custom field names](/reference/api-reference/indexing#custom-fields).

<mark style="color:green;">`POST`</mark> `https://api.neuralens.ai/search/index`

Indexes a new product. You can index up to 100 products in a single request.

Indexing is asynchronous. It may take up to an hour for newly indexed products to reflect in Search.

#### Request Headers

| Header                     | Value                       |
| -------------------------- | --------------------------- |
| X-Neuralens-API-Key        | Bearer YOUR\_API\_KEY\_HERE |
| X-Neuralens-Application-ID | YOUR\_APPLICATION\_ID       |

#### Request Body

```json
products: [
    {
        "id": "AD176",
        "title": "Printed T-shirt",
        "categories": ["Women", "Topwear", "Tshirts"],
        "productUrl": "https://example.com/product/id/AD176",
        "images": ["https://cdn.example.com/123", "https://cdn.example.com/789"],
        "currency": "USD",
        "listPrice": 18.99,
        "salePrice": 14.99,
        "size": "L",
        "fabricPrimary": "Cotton",
        "fabricOthers": ["Viscose"],
        "brand": "H&M",
    },
    {
        ...
    }
]
```

#### Explore Indexing API

{% content-ref url="/pages/YPkLgsN7B75ucoTuEFRQ" %}
[Indexing](/reference/api-reference/indexing)
{% endcontent-ref %}

## Search API

Use the Search API to query the indexed products. The Search API is also used to apply any sorts or filters.

<mark style="color:green;">`POST`</mark> `https://api.neuralens.ai/search/query`

#### Request Headers

| Header                     | Value                       |
| -------------------------- | --------------------------- |
| X-Neuralens-API-Key        | Bearer YOUR\_API\_KEY\_HERE |
| X-Neuralens-Application-ID | YOUR\_APPLICATION\_ID       |

#### Request Body

```json
{
    "query": "shirt",
    "offset": 0,
    "limit": 20,
    "filters": [
        {
            "field": "brand",
            "values": ["H&M", "Lacoste", "Nike"]
        }
    ],
    "fields": ["id", "productUrl", "title", "images"],
    "sort": "price",
    "sortOrder": "desc",
    "analytics": {
        "userId": "8769"
    }
}
```

#### Response&#x20;

```json
{
    "qid": "59f7e4d1-1364-4903-9f92-8691af26d7e2",
    "hasNextPage": true,
    "results": [    
        {
            "id": "AD176",
            "title": "Printed T-shirt",
            "images": ["https://cdn.example.com/123", "https://cdn.example.com/789"],
            "productUrl": "https://example.com/product/AD176"
        },
        {
            ...
        }
    ],
    "filters": [
        {
            "field": "size",
            "label": "Size",
            "values": ["S", "M", "L", "XL", "XXL"],
            "is_applied": false
        },
        ...
    ],
    "sorts": [
        {
            "field": "relevance",
            "order": "desc",
            "label": "Relevance",
            "is_applied": true
        },
        {
            "field": "price",
            "order": "asc",
            "label": "Price - Low to High",
            "is_applied": false
        },
        ...
    ]
    "pagination": {
        "total": 45,
        "current_offset": 0,
        "next_offset": 20
    }
}
```

#### Explore Search API

{% content-ref url="/pages/nyFhqw1VFyeCgz9Vacee" %}
[Search](/reference/api-reference/search)
{% endcontent-ref %}


# API Reference

Dive into the specifics of each API endpoint by checking out our complete documentation.

## Indexing

Indexing is how you add your products to the search engine.

{% content-ref url="/pages/YPkLgsN7B75ucoTuEFRQ" %}
[Indexing](/reference/api-reference/indexing)
{% endcontent-ref %}

## Search

Use the Search API to query the indexed products.

{% content-ref url="/pages/nyFhqw1VFyeCgz9Vacee" %}
[Search](/reference/api-reference/search)
{% endcontent-ref %}

## Autocomplete

The Autocomplete API returns suggestions for the autocompleter.

{% content-ref url="/pages/KgP5r4KxAiCf4diCcfNO" %}
[Autocomplete](/reference/api-reference/autocomplete)
{% endcontent-ref %}

## Event Tracking

Event Tracking allows Neuralens to learn from a user's behaviour and personalise the results for them.

{% content-ref url="/pages/WO5mz8GCqOIMR2AGd3EI" %}
[Event tracking](/reference/api-reference/event-tracking)
{% endcontent-ref %}

##


# Indexing

## Indexing API

Indexing is how you add your products to the search engine. For better understanding by the Neuralens Engine and better relevance, refer the set of [standardized fields](#standardized-fields). If you product attributes are not in the standardized set, you can use [custom field names](#custom-fields).

<mark style="color:green;">`POST`</mark> `https://api.neuralens.ai/search/index`

Indexes a new product. You can index up to 100 products in a single request.

Indexing is asynchronous. It may take up to an hour for newly indexed products to reflect in Search.

### Request Headers

| Header                     | Value                       |
| -------------------------- | --------------------------- |
| X-Neuralens-API-Key        | Bearer YOUR\_API\_KEY\_HERE |
| X-Neuralens-Application-ID | YOUR\_APPLICATION\_ID       |

### Request Params

<table><thead><tr><th width="138">Param</th><th>Value</th></tr></thead><tbody><tr><td>partition</td><td>Partition field's value (required in case partitioning is done)</td></tr></tbody></table>

Let's say `partition` is enabled on field "continent", then when sending request for the continent "asia", partition will be `asia`

### Request Body

```json
[
    {
        "id": "AD176",
        "title": "Printed T-shirt",
        "categories": ["Women", "Topwear", "Tshirts"],
        "productUrl": "https://example.com/product/id/AD176",
        "images": ["https://cdn.example.com/123", "https://cdn.example.com/789"],
        "currency": "USD",
        "listPrice": 18.99,
        "salePrice": 14.99,
        "size": "L",
        "fabricPrimary": "Cotton",
        "fabricOthers": ["Viscose"],
        "brand": "H&M",
        // Any other custom fields
    },
    {
        ...
    }
]
```

### Response

```json
{
    "status": "success",    // or failure
    "message": ""    // failure message
}
```

### Standardized Fields

{% hint style="info" %}
These fields allow Neuralens to understand what the product is, and greatly affect the search performance.
{% endhint %}

Standardized fields are product fields that have a special meaning in the Neuralens system. Use the standardized fields instead of custom fields wherever a standardized field exists. That means, instead of adding the product name to a field called "name", use the standardized "title" field. For a field like Brand, or Fabric, use custom fields.&#x20;

The following fields are standardized:

<table><thead><tr><th width="155">Field Name</th><th width="129">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>The product's unique identifier. A call to /search/index for an id which already exists will overwrite the existing data</td></tr><tr><td>title</td><td>string</td><td>The product's name</td></tr><tr><td>productUrl</td><td>string</td><td>The URL to the product details page of the product. The url that is opened on clicking the product.</td></tr><tr><td>categories</td><td>list of string</td><td>The category hierarchy of the product in the catalog. The categories should be ordered with the top level hierarchy coming first in the list. <br><code>NOTE: </code><strong><code>last value of categories will be treated as product type</code></strong><br>eg: ["Women", "Topwear", "Tshirts"],</td></tr><tr><td>images</td><td>list of string</td><td>eg: ["https://cdn.example.com/123", "https://cdn.example.com/789"]</td></tr><tr><td>listPrice</td><td>float</td><td>The original price of the product </td></tr><tr><td>salePrice</td><td>float</td><td>The discounted price</td></tr></tbody></table>

### Custom Fields

Any attribute which is not a part of the standardized fields set is a custom field.

The following types are supported in custom fields:

* String
* Integer
* Float
* Boolean
* Datetime
* List (lists of Strings, Integers, Floats are supported. A list should have values of only one type)


# Search

## Search API

Use the Search API to query the indexed products. The Search API is also used to apply any sorts or filters.

<mark style="color:green;">`POST`</mark> `https://api.neuralens.ai/search/query`

### Request Headers

| Header                     | Value                       |
| -------------------------- | --------------------------- |
| X-Neuralens-API-Key        | Bearer YOUR\_API\_KEY\_HERE |
| X-Neuralens-Application-ID | YOUR\_APPLICATION\_ID       |

### Request Params

<table><thead><tr><th width="138">Param</th><th>Value</th></tr></thead><tbody><tr><td>partition</td><td>Partition field's value (required in case partitioning is done)</td></tr></tbody></table>

Let's say `partition` is enabled on field "continent", then when sending request for the continent "asia", partition will be `asia`

### Request Body&#x20;

```json
{
    "query": "shirt",
    "offset": 0,
    "limit": 20,
    "filters": [
        {
            "field": "brand",
            "values": ["H&M", "Lacoste", "Nike"]
        }
    ],
    "fields": ["id", "productUrl", "title", "images"],
    "sorts": [
        {
            "field": "inStock",
            "order": "desc"
        },
        {
            "field": "salePrice",
            "order": "asc"
        }
    ],
    "sortOrder": "desc",
    "analytics": {
        "userId": "8769"
    }
}
```

`query` The search query text

`offset, limit` For pagination. offset is the index at which the requested page starts, limit is the number of results required on the page

`filters` Filters to be applied on the results

`sorts` Sorts applied by the user, if there are are more than one sort, next sort will only be used in case of tiebreaker from previous ones

`fields` Fields required in the search response

`analytics` Metadat required for performance tuning and personalisation

### Response

```json
{
    "qid": "59f7e4d1-1364-4903-9f92-8691af26d7e2",
    "results": [    
        {
            "id": "AD176",
            "title": "Printed T-shirt",
            "images": ["https://cdn.example.com/123", "https://cdn.example.com/789"],
            "productUrl": "https://example.com/product/AD176"
        },
        {
            ...
        }
    ],
    "filters": [
        {
            "field": "size",
            "label": "Size",
            "values": [
                {"value": "S", "count": 10, "is_applied": false}, 
                {"value": "M", "count": 10, "is_applied": false}, 
                {"value": "L", "count": 10, "is_applied": false},  
            ],
        },
        ...
    ],
    "sorts": [
        {
            "field": "relevance",
            "order": "desc",
            "label": "Relevance",
            "is_applied": true
        },
        {
            "field": "price",
            "order": "asc",
            "label": "Price - Low to High",
            "is_applied": false
        },
        ...
    ]
    "pagination": {
        "total": 45,
        "current_offset": 0,
        "next_offset": 20
    }
}
```

`qid` Unique id of the query

`results` List of search results

`filters` List of applicable filters, and their values. `is_applied` tells whether the current filter is already applied.

`sorts` List of applicable sorts, and their values. `is_applied` tells whether the current sort is applied.


# Autocomplete

## Autocomplete API

The Autocomplete API returns suggestions for the autocompleter, as the user types the query in the search bar. It is suggested to wait at least 300ms between keystrokes before calling the API.&#x20;

<mark style="color:green;">`POST`</mark> `https://api.neuralens.ai/search/autocomplete`

Autocomplete API can return lists of query suggestions, and products that match the query. Use appropriate `limit` values as per use case.

### Request Headers

| Header                     | Value                       |
| -------------------------- | --------------------------- |
| X-Neuralens-API-Key        | Bearer YOUR\_API\_KEY\_HERE |
| X-Neuralens-Application-ID | YOUR\_APPLICATION\_ID       |

### Request Params

<table><thead><tr><th width="138">Param</th><th>Value</th></tr></thead><tbody><tr><td>partition</td><td>Partition field's value (required in case partitioning is done)</td></tr></tbody></table>

Let's say `partition` is enabled on field "continent", then when sending request for the continent "asia", partition will be `asia`

### Request Body

```json
{
    "query": "appl",
    "limit": {
        "text": 10,
        "products": 10
    },
    "fields": ["id","title","images","productUrl"],
    "analytics": {
        "userId": "87023"
    }
}
```

`query` The text typed by the user

`limit` *text* limit and *products* limits are the number of text results and product results required in response. One of these is required.

`fields` Fields required in response

`analytics` For personalization and performance tuning

### Response

```json
{
    "qid": "4fcb0b58-e040-4aa0-96cf-859692f77f53",
    "results": {
        "text": [
            {
                "title": "Apple",
                "images": ["https://cdn.example.com/123"],
            },
            ...
        ],
        "products": [
            {
                "id": "AD176",
                "type": "product",
                "title": "Apple - Fuji",
                "images": ["https://cdn.example.com/123", "https://cdn.example.com/789"],
                "productUrl": "https://example.com/product/AD176"
            },
            ...
        ]
    }
}
```


# Event tracking

## Event Tracking API

Event Tracking allows Neuralens to learn from a user's behavior and personalize the results for them.

<mark style="color:green;">`POST`</mark> `https://api.neuralens.ai/analytics/event`

### Request Headers

| Header                     | Value                       |
| -------------------------- | --------------------------- |
| X-Neuralens-API-Key        | Bearer YOUR\_API\_KEY\_HERE |
| X-Neuralens-Application-ID | YOUR\_APPLICATION\_ID       |

### Request Body

```json
{
    "uid": "3845",
    "items": [
        {
            "id": "AV768"
        }
    ],
    "query": "solid wood chair",
    "page": "SEARCH_RESULT_PAGE",
    "event": "CLICK_PRODUCT",
    "index": 3,
    "geo": {
        "lat": 31.34956697190882, 
        "long": 78.44615274878441,
        "region": "MG Road",
    },
    "timestamp": 1715644800
}
```

`uid` user id. For anonymous users, send anonymous uuids if available, or null

`items` id of the product for which the event is triggered. This can contain multiple product ids in case event=PURCHASE. In all other cases it should contain a single product id.

`index` The index of the product/suggestion that is viewed, clicked, favorited or added to cart. Index values start at 0&#x20;

`query` The search query text. For example, if a user adds items to cart from search results page, the ADD\_TO\_CART event object should contain the respective query text.&#x20;

`geo` Location details of the user at the time of event. lat and long are the user's coordinates. *region* is the name of the region at the level at which user behavior matters in your scenario. This could be a locality, city, city-country, state, or any other internal nomenclature you use depending upon the use case.

**Values for Page**

The Page parameter defines the page where the event took place

* SEARCH\_RESULT\_PAGE - Search Result Page
* AUTOCOMPLETE - Search Autocomplete
* CATEGORY\_PAGE - All merchandising pages
* PRODUCT\_PAGE - Product Details Page

**Values for Event**

The Event parameter defines the type of event

* VIEW\_PRODUCT
* CLICK\_PRODUCT
* VIEW\_SUGGESTION (Autocomplete suggestion)
* CLICK\_SUGGESTION (Autocomplete suggestion)
* LAND\_PRODUCT\_PAGE
* FAVORITE
* SHARE
* ADD\_TO\_CART
* PURCHASE

### Response&#x20;

```json
{
    "status": "success",    // or failure
    "message": ""    // failure message
}
```