Index Engine SDKs

Production-ready clients to call the /api/recommend endpoint from your backend or frontend. All SDKs include error handling, retry logic, and support for hydrated recommendations.

Python SDK

Production Ready PyPI Available

Installation

pip install indexngin

Requires Python 3.7+

Quick Start

from indexngin import IndexNginClient

# Initialize client
client = IndexNginClient(
    base_url="https://api.indexngin.com",
    api_key="ak_xxx.as_xxx"
)

# Basic recommendations (IDs only)
recs = client.recommend(
    user_id=1,
    bname="beautyskincare",
    top_n=10,
    model="cf"
)

print(recs)

Advanced Usage

# Hydrated recommendations with specific fields
hydrated = client.recommend(
    user_id=1,
    bname="beautyskincare",
    top_n=10,
    expand=True,
    fields=["title", "image_url", "price", "brand"]
)

# Or use the convenience method
hydrated2 = client.recommend_hydrated(
    user_id=1,
    bname="beautyskincare",
    top_n=10,
    fields=["title", "image_url", "price"]
)

# With custom retry settings
client = IndexNginClient(
    base_url="https://api.indexngin.com",
    api_key="ak_xxx.as_xxx",
    timeout=15.0,
    max_retries=5,
    backoff_factor=1.0
)

# Error handling
try:
    recs = client.recommend(user_id=1, bname="beautyskincare")
except IndexNginError as e:
    print(f"Error: {e}")

Features

  • Automatic retry with exponential backoff
  • Rate limit detection and handling
  • Hydrated recommendations with field selection
  • Type hints for better IDE support
  • Customizable timeout and retry settings
Full Documentation

View the complete Python SDK documentation including all methods and configuration options on PyPI.

JavaScript / TypeScript SDK

Production Ready

Installation

npm install @indexngin/sdk
yarn add @indexngin/sdk

Usage

import { IndexNginClient, IndexNginError } from '@indexngin/sdk';

const client = new IndexNginClient({
  baseUrl: 'https://api.indexngin.com',
  apiKey: 'ak_xxx.as_xxx',
  timeout: 10000,
  maxRetries: 3
});

try {
  // Basic recommendations
  const recs = await client.recommend({
    userId: '123',
    bname: 'beautyskincare',
    topN: 10
  });

  // Hydrated recommendations
  const hydrated = await client.recommend({
    userId: '123',
    bname: 'beautyskincare',
    topN: 10,
    expand: true,
    fields: ['title', 'imageUrl', 'price']
  });

  console.log(recs);
} catch (error) {
  if (error instanceof IndexNginError) {
    console.error('API Error:', error.message);
  }
}

Search Analytics Helper

For browser-side click and conversion tracking, load the helper shipped with the app instead of copying raw fetch calls. 

<script src="/search-analytics.js"></script>
<script>
  const analytics = window.IndexNginAnalytics.create({
    endpoint: '/api/analytics/events',
    pipelineSlug: 'rh_products_na'
  });

  analytics.trackClick({
    queryId,
    query: 'rugs',
    documentId: 'sku-123',
    position: 1,
    sessionId: 'sess-1'
  });

  analytics.trackConversion({
    queryId,
    query: 'rugs',
    documentId: 'sku-123',
    conversionType: 'purchase',
    value: 249.00,
    sessionId: 'sess-1'
  });
</script>

The helper supports trackClick() and trackConversion() on top of the search query_id returned by the public search API. Recommended conversion types include pdp_view, add_to_cart, checkout_start, and purchase.

Under Development

JavaScript SDK is being finalized. Expected release: Q2 2024

Java SDK

Beta

Maven Installation

<dependency>
    <groupId>com.indexngin</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0.0-beta</version>
</dependency>

Usage

import com.indexngin.IndexNginClient;
import com.indexngin.IndexNginException;

public class Example {
    public static void main(String[] args) {
        IndexNginClient client = new IndexNginClient.Builder()
            .baseUrl("https://api.indexngin.com")
            .apiKey("ak_xxx.as_xxx")
            .timeout(Duration.ofSeconds(10))
            .maxRetries(3)
            .build();

        try {
            // Basic recommendations
            RecommendationResponse response = client.recommend(
                RecommendationRequest.builder()
                    .userId("123")
                    .bname("beautyskincare")
                    .topN(10)
                    .build()
            );

            // Hydrated recommendations
            RecommendationResponse hydrated = client.recommend(
                RecommendationRequest.builder()
                    .userId("123")
                    .bname("beautyskincare")
                    .topN(10)
                    .expand(true)
                    .fields(Arrays.asList("title", "image_url", "price"))
                    .build()
            );

            System.out.println(response.getRecommendations());
        } catch (IndexNginException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Go SDK

Beta

Installation

go get github.com/indexngin/go-sdk

Usage

package main

import (
    "fmt"
    "log"
    indexngin "github.com/indexngin/go-sdk"
)

func main() {
    client := indexngin.NewClient(
        "https://api.indexngin.com",
        "ak_xxx.as_xxx",
        indexngin.WithTimeout(10*time.Second),
        indexngin.WithMaxRetries(3),
    )
    
    // Basic recommendations
    req := &indexngin.RecommendationRequest{
        UserID: "123",
        BName:  "beautyskincare",
        TopN:   10,
    }
    
    recs, err := client.Recommend(req)
    if err != nil {
        log.Fatal(err)
    }
    
    // Hydrated recommendations
    hydratedReq := &indexngin.RecommendationRequest{
        UserID: "123",
        BName:  "beautyskincare",
        TopN:   10,
        Expand: true,
        Fields: []string{"title", "image_url", "price"},
    }
    
    hydrated, err := client.Recommend(hydratedReq)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Recommendations: %v\n", recs)
}

PHP SDK

Beta

Installation

composer require indexngin/sdk

Usage

<?php

require_once 'vendor/autoload.php';

use IndexNgin\Client;
use IndexNgin\Exception\IndexNginException;

$client = new Client(
    'https://api.indexngin.com',
    'ak_xxx.as_xxx',
    [
        'timeout' => 10,
        'max_retries' => 3
    ]
);

try {
    // Basic recommendations
    $recs = $client->recommend([
        'user_id' => 123,
        'bname' => 'beautyskincare',
        'top_n' => 10
    ]);

    // Hydrated recommendations
    $hydrated = $client->recommend([
        'user_id' => 123,
        'bname' => 'beautyskincare',
        'top_n' => 10,
        'expand' => true,
        'fields' => ['title', 'image_url', 'price']
    ]);

    print_r($recs);
} catch (IndexNginException $e) {
    echo 'Error: ' . $e->getMessage();
}

Ruby SDK

Coming Soon

Installation

gem install indexngin-sdk

Usage Preview

require 'indexngin'

client = IndexNgin::Client.new(
  base_url: 'https://api.indexngin.com',
  api_key: 'ak_xxx.as_xxx',
  timeout: 10,
  max_retries: 3
)

# Basic recommendations
recs = client.recommend(
  user_id: 123,
  bname: 'beautyskincare',
  top_n: 10
)

# Hydrated recommendations
hydrated = client.recommend(
  user_id: 123,
  bname: 'beautyskincare',
  top_n: 10,
  expand: true,
  fields: ['title', 'image_url', 'price']
)

puts recs
Planned Release

Ruby SDK is scheduled for release in Q3 2024. Sign up for updates.

API Endpoint Reference

Base URL

https://api.indexngin.com

Recommendation Endpoint

GET /api/recommend
Parameter Type Required Description
user_id string/integer Yes Unique identifier for the user
bname string Yes Business/tenant identifier
top_n integer No Number of recommendations (default: 10)
model string No Model type (default: "cf")
expand string No Set to "product" to join with product index
fields string No Comma-separated list of fields to return
Authentication

All requests require an API key in the X-API-Key header. Generate API keys in your business dashboard.

Click Tracking Helper

Search responses include a query_id. Send that back to Index Engine when a user clicks a result so analytics can report click-through rate, no-click queries, and top clicked documents.

async function trackSearchClick({
  apiKey,
  queryId,
  pipelineSlug,
  query,
  documentId,
  position,
  sessionId
}) {
  await fetch('/api/analytics/events', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': apiKey
    },
    body: JSON.stringify({
      events: [
        {
          type: 'click',
          pipelineSlug,
          queryId,
          query,
          documentId,
          position,
          sessionId
        }
      ]
    })
  });
}

// Example usage after rendering search results
resultCard.addEventListener('click', () => {
  trackSearchClick({
    apiKey: 'ak_...as_...',
    queryId: response.query_id,
    pipelineSlug: response.pipeline,
    query: response.q,
    documentId: hit.id,
    position: index + 1,
    sessionId: window.sessionStorage.getItem('search_session_id') || undefined
  }).catch(console.error);
});
Endpoint: POST /api/analytics/events. Supported events today: click and conversion, with recommended conversion types like pdp_view, add_to_cart, checkout_start, and purchase.