Doofinder

https://docs.doofinder.com/
Admin
Doofinder is a search platform that provides APIs for performing searches, managing search engines...
Tokens:58,301
Snippets:342
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Sort Parameters Example

Source: https://docs.doofinder.com/api/search/v6

Provides an example of how to sort search results by multiple fields in ascending or descending order.

```url
sort[0][price]=asc&sort[1][brand]=desc
```

--------------------------------

### Example Search Zone Endpoints

Source: https://docs.doofinder.com/api/management/v2/stats

These examples show the base URL structure for different search zones. Replace `{search-zone}` with your datacenter's code.

```bash
https://eu1-api.doofinder.com
```

```bash
https://us1-api.doofinder.com
```

--------------------------------

### Get Search Engine Details Response

Source: https://docs.doofinder.com/api/management/v2

Example response for retrieving search engine configuration details. This includes index presets, data sources, and general settings.

```json
{
  "currency": "EUR",
  "hashid": "123456789012345678901234567890ab",
  "indices": [
    {
      "name": "product",
      "preset": "product",
      "options": { },
      "datasources": [
        {
          "type": "file",
          "options": {
            "url": "https://yourserver/your_data_feed.xml"
}
}
]
}
],
  "inactive": false,
  "language": "es",
  "locale": "es-ES",
  "name": "My Search Engine",
  "search_url": "https://eu1-search.doofinder.com",
  "stopwords": false,
  "default": false,
  "platform": "shopify",
  "has_grouping": false,
  "store_id": "e9d6fcd2-0262-4094-bf3c-671ec5da5455"

}
```

--------------------------------

### Update Search Engine Response Example

Source: https://docs.doofinder.com/api/management/v2

Example JSON response after successfully updating a search engine. Includes updated fields and metadata like hashid and search_url.

```json
{
  "currency": "EUR",
  "hashid": "123456789012345678901234567890ab",
  "indices": [
    {
      "name": "product",
      "preset": "product",
      "options": { },
      "datasources": [
        {
          "type": "file",
          "options": {
            "url": "https://yourserver/your_data_feed.xml"
}
}
]
}
],
  "inactive": false,
  "language": "es",
  "locale": "es-ES",
  "name": "My Search Engine",
  "site_url": "http://my.web.site",
  "search_url": "https://eu1-search.doofinder.com",
  "stopwords": false,
  "default": false,
  "platform": "shopify",
  "has_grouping": false,
  "store_id": "e9d6fcd2-0262-4094-bf3c-671ec5da5455"
}
```

--------------------------------

### Example Response for Multi-Item Retrieval

Source: https://docs.doofinder.com/api/management/v2

This is an example of a successful response when retrieving multiple items from a temporal index, showing the found status and item details for each requested ID.

```json
[
  {
    "id": "1234",
    "found": true,
    "item": {
      "title": "Item Title",
      "link": "http://www.example.com/img/1234.png",
      "id": "1234",
      "df_manual_boost": 1,
      "categories": [
        "cat1",
        "cat2"
]
}
}

]
```

--------------------------------

### Facets Example

Source: https://docs.doofinder.com/api/search/v6

Shows how to configure term and range facets for aggregating search results.

```url
facets[0][field]=brand&facets[0][size]=10&facets[1][field]=best_price
```

--------------------------------

### API Key Authentication Example

Source: https://docs.doofinder.com/api/management/v2/stats

Demonstrates how to authenticate using an API key by including it in the Authorization header.

```http
Authorization: Token ab46030xza33960aac71a10248489b6c26172f07
```

--------------------------------

### Filter Parameters Example

Source: https://docs.doofinder.com/api/search/v6

Illustrates how to apply filters to narrow down search results, including range filters.

```url
filter[color][]=blue&filter[color][]=red&filter[size][]=M&filter[size][]=S&filter[price][gte]=4.36&filter[price][lt]=99
```

--------------------------------

### API Key Example

Source: https://docs.doofinder.com/api/management/v2

A valid format for a Doofinder API key.

```text
ab46030xza33960aac71a10248489b6c26172f07
```

--------------------------------

### GET Search Response Sample

Source: https://docs.doofinder.com/api/search/v6

This is a sample JSON response for a successful GET search request. It includes facets, query name, and search results with item details.

```json
{
  "custom_results_id": 5,
  "facets": [
    {
      "brand": {
        "terms": {
          "items": [
            {
              "name": "Adidas",
              "count": 5
            },
            {
              "name": "Nike",
              "count": 3
            }
          ],
          "selected": [ ]
        }
      }
    }
  ],
  "query_name": "fuzzy",
  "results": [
    {
      "description": "The best product description ever",
      "dfid": "1234567890abcdef1234567890abcdef@product@1234567890abcdef",
      "id": "my_id",
      "image_url": "http://www.example.com/images/alt_product_image.jpg",
      "title": "My item",
      "url": "http://www.example.com/alt_product_description.htm"
    }
  ],
  "total": 1
}
```

--------------------------------

### Update Search Engine Request Payload Example

Source: https://docs.doofinder.com/api/management/v2

Example JSON payload for updating a search engine. Includes fields like currency, locale, name, and platform.

```json
{
  "currency": "EUR",
  "language": "es",
  "locale": "es-ES",
  "name": "My Search Engine",
  "site_url": "http://my.web.site",
  "stopwords": false,
  "default": false,
  "platform": "shopify",
  "has_grouping": false,
  "store_id": "e9d6fcd2-0262-4094-bf3c-671ec5da5455"
}
```

--------------------------------

### Exclude Parameters Example

Source: https://docs.doofinder.com/api/search/v6

Demonstrates how to use exclude parameters for negative filtering, including range filters.

```url
exclude[color][]=blue&exclude[color][]=red&exclude[size]=M&exclude[size]=S&exclude[price][gte]=4.36&exclude[price][lt]=99
```

--------------------------------

### Sale Confirmation Response Sample

Source: https://docs.doofinder.com/api/management/v2/stats

Example of a successful response after confirming a sale. Typically returns null upon successful registration.

```json
null
```

--------------------------------

### Init session

Source: https://docs.doofinder.com/api/search/v6

Starts a session identified by a session_id. This session is used to group user interactions, such as clicking banners or completing checkouts.

```APIDOC
## PUT /6/{hashid}/stats/init

### Description
Starts a session identified by a session_id. The session is used to "group" events.

### Method
PUT

### Endpoint
`https://{search_zone}-search.doofinder.com/6/{hashid}/stats/init`

### Path Parameters
- **hashid** (string) - Required - Unique id of a search engine.

### Request Body
- **session_id** (string) - Required - <= 32 characters - Identifier of search session
- **user_id** (string) - Optional - <= 36 characters - Identifier of user

### Request Example
```json
{
  "session_id": "string",
  "user_id": "string"
}
```

### Response
#### Success Response (200)
OK
- **status** (string) - Indicates the status of the registration.

#### Response Example
```json
{
  "status": "registered"
}
```
```

--------------------------------

### Get Clicks with Users

Source: https://docs.doofinder.com/api/management/v2/stats

Counts the number of different users and products in clicks for a time period.

```APIDOC
## GET /api/v2/stats/clicks/users

### Description
Counts the number of different users and products in clicks for a time period.

### Method
GET

### Endpoint
https://{search_zone}-api.doofinder.com/api/v2/stats/clicks/users

### Query Parameters
- **from** (string) - Required - Start date of the period in the format of UNIX timestamp or YYYYMMDD.
- **to** (string) - Required - End date of the period in the format of UNIX timestamp or YYYYMMDD.
- **hashids** (Array of strings) - Optional - Unique id of the search engine. Arrays parameters must be in the format `param[]=value`.
- **hashid** (Array of strings) - Optional - Deprecated.
- **tz** (string) - Optional - The timezone for the given dates, by default, assumes ETC/UTC. Example: tz=Europe/Madrid.
- **device** (string) - Optional - Filter by kind of device. Enum: "desktop", "mobile".
- **format** (string) - Optional - Indicates which response format should be used. Default: "json". Enum: "json", "csv".
- **aggregate** (boolean) - Optional - Flag to indicate when to aggregate all Search Engines stats data. Default: true.
- **indices** (object) - Optional - Filter by index name. Parameters: name (string, required), hashid (string, required). Format: indices[i][name]=value&indices[i][hashid]=hashid.
- **query** (string) - Optional - An string used to filter stats by input query.
- **dfid** (string) - Optional - Filter by a doofinder item id.
- **product_type** (Array of strings) - Optional - Filter by the type of product. Items Enum: "search", "banner", "custom_result", "recommendation", "quizz", "aichat".

### Authorizations
_api_token_ _jwt_token_
```

--------------------------------

### Initialize Session Payload

Source: https://docs.doofinder.com/api/search/v6

Use this payload to start a new session. It requires a session ID and can optionally include a user ID.

```json
{
  "session_id": "string",
  "user_id": "string"
}
```

--------------------------------

### Get Redirects Stats

Source: https://docs.doofinder.com/api/management/v2/stats

Gets redirection statistics and how many times users make use of them in a time period.

```APIDOC
## Get Redirects Stats

### Description
Gets redirection statistics and how many times users make use of them in a time period.

### Method
GET

### Endpoint
/api/v2/stats/redirects

### Query Parameters
- **from** (string) - Required - Start date of the period in the format of UNIX timestamp or YYYYMMDD.
- **to** (string) - Required - End date of the period in the format of UNIX timestamp or YYYYMMDD.
- **hashids** (Array of strings) - Optional - Unique id of the search engine. Arrays parameters must be in the format `param[]=value`.
- **hashid** (Array of strings) - Deprecated
- **id** (integer) - Optional - Filter by the unique id of a redirection.
- **tz** (string) - Optional - The timezone for the given dates, by default, assumes ETC/UTC.
- **format** (string) - Optional - Indicates which response format should be used (json or csv).
- **aggregate** (boolean) - Optional - Flag to indicate when to aggregate all Search Engines stats data.
- **query** (string) - Optional - An string used to filter stats by input query.

### Responses
#### Success Response (200)
OK

### Response Example
```json
{
  "results": [
    {
      "count": 12,
      "id": 9771,
      "link": "https://example.com/redirection"
    }
  ],
  "total": 1,
  "total_count": 12
}
```
```

--------------------------------

### Get Top Results Searches Stats

Source: https://docs.doofinder.com/api/management/v2/stats

Gets the most commonly obtained results in searches during a time period, filterable by brand or categories.

```APIDOC
## Get Top Results Searches Stats

### Description
Gets the most commonly obtained results in searches during a time period, filterable by brand or categories.

### Method
GET

### Endpoint
/api/v2/stats/results/top

### Query Parameters
- **from** (string) - Required - Start date of the period in the format of UNIX timestamp or YYYYMMDD.
- **to** (string) - Required - End date of the period in the format of UNIX timestamp or YYYYMMDD.
- **hashids** (Array of strings) - Optional - Unique id of the search engine. Arrays parameters must be in the format `param[]=value`.
- **query** (string) - Optional - An string used to filter stats by input query.
- **dfid** (string) - Optional - Filter by a doofinder item id.
- **device** (string) - Optional - Filter by kind of device (desktop or mobile).
- **metric** (string) - Optional - Parameter to group and filter the data based on your choice, which can be either 'brand' or 'categories'.
- **limit** (integer) - Optional - Maximum number of items to return with a minimum of 1 item and a maximum of 1000.

### Responses
#### Success Response (200)
Stats retrieved.
```

--------------------------------

### Search Query (GET)

Source: https://docs.doofinder.com/api/search/v6

Retrieve search results by making a GET request to the search endpoint. This method is suitable for simpler queries.

```APIDOC
## GET /6/{hashid}/_search

### Description
Searches through indexed items of a search engine using a GET request.

### Method
GET

### Endpoint
https://{search_zone}-search.doofinder.com/6/{hashid}/_search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search term.
- **rpp** (integer) - Optional - Results per page (max 100).
- **page** (integer) - Optional - Page number of the results to return.
- **indices** (Array of strings) - Optional - Restrict the search to one or more indices (e.g. ["product", "page"]).
- **filter** (object) - Optional - Filter parameters for items. Keys are field names, values are lists of terms or range objects (gte, lte, gt, lt).
- **exclude** (object) - Optional - Negative filters. Same structure as filter.
- **facets** (Array of objects) - Optional - Aggregations to compute. Each entry must include a "field" key.
- **filter_execution** (string) - Optional - Enum: "and" "or" Boolean logic applied to filters. Default is "and".
- **sort** (Array of objects) - Optional - Sort criteria. Each entry is a map of field name to direction (e.g. [{"price": "asc"}]).
- **query_name** (string) - Optional - Enum: "match_and" "match_or" "fuzzy" Force a specific query type.
- **session_id** (string) - Optional - <= 32 characters - Identifier of search session.
- **user_id** (string) - Optional - <= 36 characters - Identifier of user.
- **stats** (boolean) - Optional - Enable/Disable this search in stats reports. Default: true.
- **auto_filters** (boolean) - Optional - Enable/Disable auto filters feature. Default: false.
- **custom_results** (boolean) - Optional - Enable/Disable custom results feature. Default: true.
- **excluded_results** (boolean) - Optional - Enable/Disable excluded items feature. Default: true.
- **grouping** (boolean) - Optional - Enable/Disable grouping of variants as single items.
- **with_variants** (Array of strings) - Optional - When grouping is active, include a df_variants array in each hit with the listed fields from each variant document.
- **skip_auto_filters** (Array of strings) - Optional - Fields to exclude from auto_filters processing.
- **skip_top_facet** (Array of strings) - Optional - Fields to exclude from top_facet processing.
- **title_facet** (boolean) - Optional - Enable/Disable title_facet feature. Default: false.
- **top_facet** (boolean) - Optional - Enable/Disable top_facet feature. Default: false.

### Responses
#### Success Response (200)
OK
- **custom_results_id** (integer) - 
- **facets** (Array of objects) - 
- **query_name** (string) - 
- **results** (Array of objects) - 
- **total** (integer) - 

#### Response Example
```json
{
  "custom_results_id": 5,
  "facets": [
    {
      "brand": {
        "terms": {
          "items": [
            {
              "name": "Adidas",
              "count": 5
            },
            {
              "name": "Nike",
              "count": 3
            }
          ],
          "selected": []
        }
      }
    }
  ],
  "query_name": "fuzzy",
  "results": [
    {
      "description": "The best product description ever",
      "dfid": "1234567890abcdef1234567890abcdef@product@1234567890abcdef",
      "id": "my_id",
      "image_url": "http://www.example.com/images/alt_product_image.jpg",
      "title": "My item",
      "url": "http://www.example.com/alt_product_description.htm"
    }
  ],
  "total": 1
}
```
```

--------------------------------

### Item Schema Example

Source: https://docs.doofinder.com/api/management/v2

This JSON object demonstrates the structure of an item that can be indexed. It includes fields for identification, grouping, pricing, categories, and links. Note the specific format for categories when the index has a 'product' preset.

```json
{
  "title": "Adidas Originals Trefoil Hoodie",
  "link": "https://woocommerce.doofinder.com/product/adidas-originals-trefoil-hoodie/",
  "image_link": "https://woocommerce.doofinder.com/wp-content/uploads/2024/02/suda-6-scaled.jpg",
  "id": "1234",
  "color": "blue",
  "price": 15.99,
  "sale_price": 11.99,
  "categories": [
    "Clothes > Hoodie",
    "Men > Hoodie"
  ]
}
```

--------------------------------

### Get index

Source: https://docs.doofinder.com/api/management/v2

Retrieves a specific search engine index.

```APIDOC
## Get 
Gets a search engine index.
##### Authorizations:
_api_token_ _jwt_token_
##### path Parameters
hashidrequired| string^[a-f0-9]{32}$ Unique id of a search engine.  
---|---  
namerequired| string^[a-z][a-z0-9_]*$ Name of an index.  
### Responses
**200**
Index retrieved.
get/api/v2/search_engines/{hashid}/indices/{name}
https://{search_zone}-api.doofinder.com/api/v2/search_engines/{hashid}/indices/{name}
https://eu1-api.doofinder.com/api/v2/search_engines/{hashid}/indices/{name}
###  Response samples 
  * 200


Content type
application/json
Copy
Expand all  Collapse all 
`{
  * "name": "product",
  * "preset": "product",
  * "options": { },
  * "datasources": [
    * {
      * "type": "file",
      * "options": {
        * "url": "https://yourserver/your_data_feed.xml"
}
}
]

}`
```

--------------------------------

### JWT Token Authentication Example

Source: https://docs.doofinder.com/api/management/v2/stats

Illustrates JWT authentication by providing a Bearer token in the Authorization header. Ensure the JWT includes `iat`, `exp`, and `name` claims.

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoidGVzdCIsImlhdCI6MTUxNjIzOTAyMn0.QX_3HF-T2-vlvzGDbAzZyc1Cd-J9qROSes3bxlgB4uk
```

--------------------------------

### Sales Data Response Sample

Source: https://docs.doofinder.com/api/management/v2/stats

Example of a successful response when retrieving sales data. It includes a list of sales results with amounts and session IDs, along with total sales count and amount.

```json
{
  "results": [
    {
      "amount": 2.2,
      "session": "24cb1eccd1cf4a67d071f2deeac75e33"
    },
    {
      "amount": 1,
      "session": "a4eaf92a223c024b7c6680dc807c3f84"
    }
  ],
  "total": 2,
  "total_amount": 3.2
}
```

--------------------------------

### Get Item

Source: https://docs.doofinder.com/api/management/v2

Retrieves a specific item from a search engine index by its ID.

```APIDOC
## GET /api/v2/search_engines/{hashid}/indices/{name}/items/{item_id}

### Description
Retrieves a specific item from a search engine index.

### Method
GET

### Endpoint
https://{search_zone}-api.doofinder.com/api/v2/search_engines/{hashid}/indices/{name}/items/{item_id}

### Parameters
#### Path Parameters
- **hashid** (string) - Required - Unique ID of a search engine.
- **name** (string) - Required - Name of an index.
- **item_id** (string) - Required - Unique identifier of an item inside an index.

### Response
#### Success Response (200)
- **title** (string) - The title of the item.
- **link** (string) - The URL associated with the item.
- **image_link** (string) - The URL of the item's image.
- **id** (string) - The unique identifier of the item.
- **color** (string) - The color of the item.
- **price** (number) - The price of the item.
- **sale_price** (number) - The sale price of the item.
- **categories** (Array of strings) - A list of categories the item belongs to.

### Response Example
```json
{
  "title": "Adidas Originals Trefoil Hoodie",
  "link": "https://woocommerce.doofinder.com/product/adidas-originals-trefoil-hoodie/",
  "image_link": "https://woocommerce.doofinder.com/wp-content/uploads/2024/02/suda-6-scaled.jpg",
  "id": "1234",
  "color": "blue",
  "price": 15.99,
  "sale_price": 11.99,
  "categories": [
    "Clothes > Hoodie",
    "Men > Hoodie"
  ]
}
```
```

--------------------------------

### Get Usage Statistics

Source: https://docs.doofinder.com/api/management/v2/stats

Retrieves the usage statistics for a given search zone.

```APIDOC
## GET /api/v2/stats/usage

### Description
Retrieves usage statistics.

### Method
GET

### Endpoint
https://{search_zone}-api.doofinder.com/api/v2/stats/usage

### Response
#### Success Response (200)
- **results** (array) - Array of usage counts and timestamps.
- **total** (integer) - Total number of results.
- **total_count** (integer) - Total count across all results.

#### Response Example
```json
{
  "results": [
    {
      "count": 12,
      "timestamp": 1581120000000
    }
  ],
  "total": 1,
  "total_count": 12
}
```
```

--------------------------------

### Get Inits Stats

Source: https://docs.doofinder.com/api/management/v2/stats

Retrieves statistics for search engine initializations within a specified time period. Supports filtering by search engine ID, device, and aggregation.

```APIDOC
## GET /api/v2/stats/inits

### Description
Retrieves statistics for search engine initializations within a specified time period. Supports filtering by search engine ID, device, and aggregation.

### Method
GET

### Endpoint
`https://{search_zone}-api.doofinder.com/api/v2/stats/inits`

### Query Parameters
- **from** (string) - Required - Start date of the period in the format of UNIX timestamp or YYYYMMDD.
- **to** (string) - Required - End date of the period in the format of UNIX timestamp or YYYYMMDD.
- **hashids** (Array of strings) - Optional - Unique id of the search engine. Arrays parameters must be in the format `param[]=value`.
- **hashid** (Array of strings) - Optional - Deprecated.
- **tz** (string) - Optional - The timezone for the given dates. Default: "Etc/UTC".
- **device** (string) - Optional - Filter by kind of device. Enum: "desktop", "mobile".
- **format** (string) - Optional - Indicates which response format should be used. Default: "json". Enum: "json", "csv".
- **aggregate** (boolean) - Optional - Flag to indicate when to aggregate all Search Engines stats data. Default: true.

### Responses
#### Success Response (200)
Stats retrieved.
- **results** (Array) - Contains statistics for each period.
  - **count** (integer) - The number of initializations.
  - **timestamp** (integer) - The timestamp for the period.
- **total** (integer) - The total number of initializations.
- **total_count** (integer) - The total count of initializations.

### Response Example
```json
{
  "results": [
    {
      "count": 12,
      "timestamp": 1581120000000
    }
  ],
  "total": 1,
  "total_count": 12
}
```
```

--------------------------------

### Get Clicks

Source: https://docs.doofinder.com/api/management/v2/stats

Counts the number of clicks in a time period, grouped by day.

```APIDOC
## GET /api/v2/stats/clicks

### Description
Counts the number of clicks in a time period, grouped by day.

### Method
GET

### Endpoint
https://{search_zone}-api.doofinder.com/api/v2/stats/clicks

### Query Parameters
- **from** (string) - Required - Start date of the period in the format of UNIX timestamp or YYYYMMDD.
- **to** (string) - Required - End date of the period in the format of UNIX timestamp or YYYYMMDD.
- **hashids** (Array of strings) - Optional - Unique id of the search engine. Arrays parameters must be in the format `param[]=value`.
- **hashid** (Array of strings) - Optional - Deprecated.
- **tz** (string) - Optional - The timezone for the given dates, by default, assumes ETC/UTC. Example: tz=Europe/Madrid.
- **device** (string) - Optional - Filter by kind of device. Enum: "desktop", "mobile".
- **format** (string) - Optional - Indicates which response format should be used. Default: "json". Enum: "json", "csv".
- **aggregate** (boolean) - Optional - Flag to indicate when to aggregate all Search Engines stats data. Default: true.
- **indices** (object) - Optional - Filter by index name. Parameters: name (string, required), hashid (string, required). Format: indices[i][name]=value&indices[i][hashid]=hashid.
- **query** (string) - Optional - An string used to filter stats by input query.
- **dfid** (string) - Optional - Filter by a doofinder item id.
- **product_type** (Array of strings) - Optional - Filter by the type of product. Items Enum: "search", "banner", "custom_result", "recommendation", "quizz", "aichat".

### Response
#### Success Response (200)
Stats retrieved.
- **results** (array) - Contains click data grouped by day.
  - **count** (integer) - The number of clicks for that day.
  - **timestamp** (integer) - The timestamp for the day.
- **total** (integer) - Total number of days with clicks.
- **total_count** (integer) - Total number of clicks.

### Response Example
```json
{
  "results": [
    {
      "count": 12,
      "timestamp": 1581120000000
    }
  ],
  "total": 1,
  "total_count": 12
}
```
```

--------------------------------

### Visually Similar Search Response Sample

Source: https://docs.doofinder.com/api/search/v6

A sample JSON response for a visually similar search query, including facets and results.

```json
{
  "custom_results_id": 5,
  "facets": [
    {
      "brand": {
        "terms": {
          "items": [
            {
              "name": "Adidas",
              "count": 5
},
            {
              "name": "Nike",
              "count": 3
}
],
          "selected": [ ]
}
}
}
],
  "query_name": "fuzzy",
  "results": [
    {
      "description": "The best product description ever",
      "dfid": "1234567890abcdef1234567890abcdef@product@1234567890abcdef",
      "id": "my_id",
      "image_url": "http://www.example.com/images/alt_product_image.jpg",
      "title": "My item",
      "url": "http://www.example.com/alt_product_description.htm"
}
],
  "total": 1
}
```

--------------------------------

### Get Checkouts

Source: https://docs.doofinder.com/api/management/v2/stats

Counts numbers of checkouts in a time period grouped by day.

```APIDOC
## GET /api/v2/stats/checkouts

### Description
Counts numbers of checkouts in a time period grouped by day.

### Method
GET

### Endpoint
https://{search_zone}-api.doofinder.com/api/v2/stats/checkouts

### Query Parameters
- **from** (string) - Required - Start date of the period in the format of UNIX timestamp or YYYYMMDD.
- **to** (string) - Required - End date of the period in the format of UNIX timestamp or YYYYMMDD.
- **hashids** (Array of strings) - Optional - Unique id of the search engine. Arrays parameters must be in the format `param[]=value`.
- **hashid** (Array of strings) - Optional - Deprecated.
- **tz** (string) - Optional - The timezone for the given dates, by default, assumes ETC/UTC.
- **device** (string) - Optional - Filter by kind of device. Enum: "desktop", "mobile".
- **format** (string) - Optional - Indicates which response format should be used. Enum: "json", "csv". Default: "json".
- **aggregate** (boolean) - Optional - Flag to indicate when to aggregate all Search Engines stats data. Default: true.
```

--------------------------------

### Get Banner Stats

Source: https://docs.doofinder.com/api/management/v2/stats

Retrieves statistics for banners, including clicks and displays.

```APIDOC
## GET /api/v2/stats/banners

### Description
Retrieves statistics for banners, including clicks and displays.

### Method
GET

### Endpoint
https://{search_zone}-api.doofinder.com/api/v2/stats/banners

### Query Parameters
- **from** (string) - Required - Start date of the period in the format of UNIX timestamp or YYYYMMDD.
- **to** (string) - Required - End date of the period in the format of UNIX timestamp or YYYYMMDD.
- **hashids** (Array of strings) - Optional - Unique id of the search engine. Arrays parameters must be in the format `param[]=value`.
- **hashid** (Array of strings) - Optional - Deprecated.
- **id** (string) - Optional - Unique id of the banner.
- **tz** (string) - Optional - The timezone for the given dates, by default, assumes ETC/UTC.
- **format** (string) - Optional - Indicates which response format should be used. Enum: "json", "csv". Default: "json".
- **aggregate** (boolean) - Optional - Flag to indicate when to aggregate all Search Engines stats data. Default: true.
- **indices** (object) - Optional - Filter by index name. Parameters: name, hashid.

### Response
#### Success Response (200)
- **results** (Array of objects) - Contains banner statistics.
  - **clicks** (integer) - Number of clicks.
  - **displays** (integer) - Number of displays.
  - **id** (integer) - Banner ID.
- **total** (integer) - Total number of results.
- **total_count** (integer) - Total count of items.

### Response Example
```json
{
  "results": [
    {
      "clicks": 2,
      "displays": 12,
      "id": 3561
    }
  ],
  "total": 1,
  "total_count": 1
}
```
```

--------------------------------

### Get Inits with Users

Source: https://docs.doofinder.com/api/management/v2/stats

Counts the number of different users in sessions for a given time period. Supports filtering by search engine ID and device.

```APIDOC
## GET /api/v2/stats/inits/users

### Description
Counts the number of different users in sessions for a given time period. Supports filtering by search engine ID and device.

### Method
GET

### Endpoint
`https://{search_zone}-api.doofinder.com/api/v2/stats/inits/users`

### Query Parameters
- **from** (string) - Required - Start date of the period in the format of UNIX timestamp or YYYYMMDD.
- **to** (string) - Required - End date of the period in the format of UNIX timestamp or YYYYMMDD.
- **hashids** (Array of strings) - Optional - Unique id of the search engine. Arrays parameters must be in the format `param[]=value`.
- **device** (string) - Optional - Filter by kind of device. Enum: "desktop", "mobile".

### Responses
#### Success Response (200)
Stats retrieved.
- **total** (integer) - The total number of sessions.
- **total_count** (integer) - The total count of sessions.
- **results** (Array) - Contains user statistics.
  - **sessions** (integer) - The number of sessions.
  - **unique_sessions** (integer) - The number of unique sessions.
  - **users** (integer) - The number of unique users.

### Response Example
```json
{
  "total": 1,
  "total_count": 1,
  "results": [
    {
      "sessions": 12170,
      "unique_sessions": 159080,
      "users": 5876
    }
  ]
}
```
```

--------------------------------

### Get Item by ID

Source: https://docs.doofinder.com/api/management/v2

Retrieves a specific item from an index using its unique identifier.

```APIDOC
## GET /api/v2/search_engines/{hashid}/indices/{name}/items/{item_id}

### Description
Gets an item from the index by its id.

### Method
GET

### Endpoint
https://{search_zone}-api.doofinder.com/api/v2/search_engines/{hashid}/indices/{name}/items/{item_id}

### Parameters
#### Path Parameters
- **hashid** (string) - Required - Unique id of a search engine.
- **name** (string) - Required - Name of an index.
- **item_id** (string) - Required - Unique identifier of an item inside an index.
```

--------------------------------

### Get Search Engine Index

Source: https://docs.doofinder.com/api/management/v2

Retrieves a specific search engine index configuration.

```json
{
  "name": "product",
  "preset": "product",
  "options": { },
  "datasources": [
    {
      "type": "file",
      "options": {
        "url": "https://yourserver/your_data_feed.xml"
      }
    }
  ]
}
```

--------------------------------

### Search Engine Usage Response Sample

Source: https://docs.doofinder.com/api/management/v2/stats

Example of a successful response when retrieving search engine usage statistics. It details the results, including brand, categories, and counts.

```json
{
  "results": [
    {
      "brand": "Garnier",
      "categories": "Perfumes",
      "count": 200
    }
  ],
  "total": 1,
  "total_count": 200
}
```

--------------------------------

### Create items in temporal index in bulk

Source: https://docs.doofinder.com/api/management/v2

Creates a list of items in the temporal index in a single bulk operation. Requires API token or JWT token for authorization.

```APIDOC
## POST /api/v2/search_engines/{hashid}/indices/{name}/temp/items

### Description
Creates a list of items in the temporal index in a single bulk operation.

### Method
POST

### Endpoint
https://{search_zone}-api.doofinder.com/api/v2/search_engines/{hashid}/indices/{name}/temp/items

### Parameters
#### Path Parameters
- **hashid** (string) - Required - Unique id of a search engine.
- **name** (string) - Required - Name of an index.
```

--------------------------------

### Get Category Merchandising

Source: https://docs.doofinder.com/api/category-merchandising

Retrieves merchandising results for a given category hash ID.

```APIDOC
## GET /category_merchandising/{hashid}

### Description
Retrieves merchandising results for a specific category page identified by its hash ID.

### Method
GET

### Endpoint
https://{zone}-category-merchandising.doofinder.com/api/1/category_merchandising/{hashid}

### Parameters
#### Path Parameters
- **hashid** (string) - Required - The unique hash ID of the category page.

#### Query Parameters
- **url** (string) - Required - The URL pattern associated with the category.

### Response
#### Success Response (200)
Returns search results for the matched category page.
- **results** (array) - List of product search results.
- **total** (integer) - Total number of results found.
- **page** (integer) - Current page number.
- **rpp** (integer) - Results per page.
- **facets** (object) - Facets available for filtering results.
- **base_filter** (array) - Base filters applied to the search.
- **filter** (array) - Additional filters applied to the search.
- **banner** (object) - Banner information to display for the category.

#### Response Example
```json
{
  "results": [
    {
      "dfid": "abc1234de@product@a1b2c3",
      "id": "SKU-001",
      "title": "Running Shoes Model X",
      "price": 99.99,
      "url": "https://example.com/products/sku-001",
      "image_url": "https://example.com/images/sku-001.jpg"
    },
    {
      "dfid": "abc1234de@product@d4e5f6",
      "id": "SKU-002",
      "title": "Trail Running Shoes Y",
      "price": 129.99,
      "url": "https://example.com/products/sku-002",
      "image_url": "https://example.com/images/sku-002.jpg"
    }
  ],
  "total": 243,
  "page": 1,
  "rpp": 50,
  "facets": {
    "brand": {
      "_type": "terms",
      "buckets": [
        {
          "key": "Nike",
          "doc_count": 42
        },
        {
          "key": "Adidas",
          "doc_count": 38
        }
      ]
    },
    "price": {
      "_type": "range",
      "buckets": [
        {
          "stats": {
            "min": 9.99,
            "max": 499.99,
            "avg": 89.5
          }
        }
      ]
    }
  },
  "base_filter": [
    {
      "field": "category",
      "values": [
        "shoes"
      ]
    }
  ],
  "filter": [],
  "banner": {
    "id": "189523",
    "image": "https://example.com/banners/shoes-banner.jpg",
    "mobile_image": "https://example.com/banners/shoes-banner-mobile.jpg",
    "html_code": null,
    "link": "https://example.com/sale/shoes",
    "target_blank": true
  }
}
```

### Error Handling
- **400 Bad Request**: The required `url` query parameter is missing.
- **401 Unauthorized**: The `Authorization` header is missing, the token is invalid, or the token does not have access to the requested search engine.
- **404 Not Found**: The category page does not exist, is inactive, or no URL pattern matches the provided `url`.
- **502 Bad Gateway**: An upstream search engine error occurred.
```

--------------------------------

### Create Search Engine Index

Source: https://docs.doofinder.com/api/management/v2

Creates a new index for a given search engine. Requires the search engine hashid, index name, preset, and optionally options and data sources.

```APIDOC
## Create Search Engine Index

### Description
Creates a new index for a search engine.

### Method
POST

### Endpoint
`/api/v2/search_engines/{hashid}/indices`

### Parameters
#### Path Parameters
- **hashid** (string) - Required - Unique id of a search engine.

#### Request Body
- **name** (string) - Required - Name of the Index.
- **preset** (string) - Required - Preset of the index.
- **options** (object) - Optional - Options for an index.
- **datasources** (Array of objects) - Optional - List of datasources of an index.

### Request Example
```json
{
  "name": "product",
  "preset": "product",
  "options": {},
  "datasources": [
    {
      "type": "file",
      "options": {
        "url": "https://yourserver/your_data_feed.xml"
      }
    }
  ]
}
```

### Responses
#### Success Response (201)
Index created.

#### Response Example
```json
{
  "name": "product",
  "preset": "product",
  "options": {},
  "datasources": [
    {
      "type": "file",
      "options": {
        "url": "https://yourserver/your_data_feed.xml"
      }
    }
  ]
}
```
```

--------------------------------

### Get Item Count

Source: https://docs.doofinder.com/api/management/v2

Retrieves the count of items within a specific index of a search engine.

```APIDOC
## GET /api/v2/search_engines/{hashid}/indices/{name}/items/_count

### Description
Retrieves the count of items within a specific index of a search engine.

### Method
GET

### Endpoint
https://{search_zone}-api.doofinder.com/api/v2/search_engines/{hashid}/indices/{name}/items/_count

### Parameters
#### Path Parameters
- **hashid** (string) - Required - The unique identifier of the search engine.
- **name** (string) - Required - The name of the index.

### Response
#### Success Response (200)
- **count** (integer) - The number of items in the index.

### Response Example
```json
{
  "count": 100
}
```
```
Tokens:
Raw