OpenCart Autocomplete API: Instant Search Suggestions

Standard OpenCart search has a basic autocomplete mechanism, but it's limited by LIKE behavior (no morphology, typos, synonyms) and doesn't scale on 10k+ SKU. AI Search provides a full REST API for autocomplete suggestions that plugs into any OpenCart theme with 1-2 lines of JavaScript. Full technical guide for developers.

What autocomplete is and why your store needs it

Autocomplete (instant suggestions as user types) cuts time-to-product by 2-4×:

On mobile autocomplete is especially critical — typing on small keyboards is slow.

REST endpoint AI Search Autocomplete API

POST https://api.ai-search.cc/v1/autocomplete

Authentication: X-API-Key header (get from ai-search.cc dashboard → Settings → API Keys).

Full API specification with all endpoints (search, autocomplete, indexing, analytics) — in Documentation.

Request format

POST /v1/autocomplete HTTP/1.1
Host: api.ai-search.cc
Content-Type: application/json
X-API-Key: VMILJRPH-G1T5F7PM-IO4MMSUD

{
  "q": "kettl",
  "store_id": 0,
  "language_id": 1,
  "limit": 10,
  "include": ["products", "categories", "queries"]
}

Response format

HTTP/1.1 200 OK
Content-Type: application/json

{
  "took_ms": 47,
  "suggestions": {
    "products": [
      {
        "id": 1234,
        "name": "Electric Kettle 1.7L Ceramic",
        "url": "https://shop.com/index.php?route=product/product&product_id=1234",
        "image": "https://shop.com/image/cache/catalog/products/1234-100x100.jpg",
        "price": "29.00",
        "score": 0.94
      }
    ],
    "categories": [{"id": 67, "name": "Kettles", "url": "...", "products_count": 47}],
    "queries": ["kettle electric", "kettle ceramic", "kettle thermal"]
  }
}

JavaScript integration

Vanilla JS (no dependencies)

const input = document.querySelector('#search-input');
const suggestionsBox = document.querySelector('#suggestions');

let debounceTimer;
input.addEventListener('input', (e) => {
  clearTimeout(debounceTimer);
  const q = e.target.value.trim();
  if (q.length < 2) { suggestionsBox.innerHTML = ''; return; }

  debounceTimer = setTimeout(async () => {
    const res = await fetch('/index.php?route=extension/aisearch/api/autocomplete&q=' + encodeURIComponent(q));
    const data = await res.json();

    suggestionsBox.innerHTML = data.suggestions.products.map(p => `
      <a href="${p.url}" class="suggestion">
        <img src="${p.image}" alt="">
        <span class="name">${p.name}</span>
        <span class="price">${p.price}</span>
      </a>
    `).join('');
  }, 200);
});

jQuery (legacy themes)

$('#search-input').on('input', _.debounce(function() {
  const q = $(this).val().trim();
  if (q.length < 2) { $('#suggestions').empty(); return; }

  $.getJSON('/index.php?route=extension/aisearch/api/autocomplete', {q: q}, function(data) {
    const html = data.suggestions.products.map(p => `
      <a href="${p.url}">${p.name} - ${p.price}</a>
    `).join('');
    $('#suggestions').html(html);
  });
}, 200));

PHP backend integration

Create catalog/controller/extension/aisearch/api.php in your OpenCart as proxy:

<?php
class ControllerExtensionAisearchApi extends Controller {
    public function autocomplete() {
        $q = $this->request->get['q'] ?? '';
        if (mb_strlen($q) < 2) {
            return $this->response->setOutput(json_encode(['suggestions' => []]));
        }

        $payload = [
            'q' => $q,
            'store_id' => (int)$this->config->get('config_store_id'),
            'language_id' => (int)$this->config->get('config_language_id'),
            'limit' => 10,
            'include' => ['products', 'categories', 'queries']
        ];

        $ch = curl_init('https://api.ai-search.cc/v1/autocomplete');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'X-API-Key: ' . $this->config->get('aisearch_api_key')
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 5);

        $response = curl_exec($ch);
        curl_close($ch);

        $this->response->addHeader('Content-Type: application/json');
        $this->response->setOutput($response);
    }
}

CORS and security

API server sets allowed origins via your domain-allowlist in dashboard:

• By default only origin of your store (license-domain) allowed
• In Settings → CORS Origins you can add dev domains, mobile apps, marketplace redirects
• Requests from unknown origins return 403 Forbidden

Rate limits

On exceeded — HTTP 429 Too Many Requests with header Retry-After: NN.

Customizing suggestions UI

1. Dropdown under input — standard UX
2. Full-screen overlay on mobile — like Amazon/Aliexpress
3. Section hints — "Popular queries", "Categories", "Products" in separate columns
4. Multi-column desktop — products in one column, categories in another

FAQ

Does API work without main AI Search module?

No. API builds on the same embeddings indexed via main module. Install AI Search first.

Can I call API directly from frontend without proxy?

Technically yes (CORS allows), but your API key ends up in DevTools. Always proxy through OpenCart controller.

What about SPA on React/Vue?

Same approach: proxy endpoint in OpenCart, frontend calls it.

Does API support category filtering?

Yes. Parameter filter_category_ids: [1,5,12] in request body.

How long is a typical request?

30-80ms server + network latency. EU locations: 100-150ms total. Pro+ via CDN-edge-proxy: 40-70ms.

Are there SDKs?

Currently REST API + PHP/JS examples. Roadmap: official npm (@aisearch/sdk) and Composer (aisearch/php-sdk) Q3 2026.