Quickstart

Pick your platform. Each route ends with the same result: your search box answers as shoppers type.

WordPress & WooCommerce

• Install the plugin, then open Gazelle Search → Gazelle Cloud.
• Paste your public and secret keys, tick Use Gazelle Cloud and save.
• Click Sync all products. Product changes sync automatically after that.

Shopify

• Install the app. Your catalog syncs on its own.
• In the theme editor, add the Gazelle Search app block.

Any other store

Add the script to every page, then give us your products with a feed or the API.

<script src="https://api.gazellesearch.com/gazelle.js"
        data-key="pk_your_public_key" async></script>

Embed script

The script looks for your theme's search box (input[type=search], name="s", name="q" and similar) and adds the dropdown to it. It also catches search boxes that appear later, such as in a mobile menu.

Results page

Without data-results-url, Enter opens Gazelle's results page over your store: filters built from your catalog (category, brand, color, size, price, stock, sale), sorting and “Show more”. Back closes it.

Recommendation blocks

Place a block anywhere; it fills itself.

<div data-gazelle-recommend="bestsellers"></div>
<div data-gazelle-recommend="similar" data-product-id="123" data-title="You may also like"></div>
<div data-gazelle-recommend="recently_viewed"></div>

<!-- On product pages, so recently viewed works -->
<div data-gazelle-product-id="123"></div>

JavaScript

// Open the results page from your own button
Gazelle.open('shoes', { brand: ['Vela'] });

// Attach to an input you create yourself
Gazelle.attach(document.querySelector('#my-search'));

// Run a search and render it your way
const res = await Gazelle.search('hedphones', { limit: 20 });

// Single-page apps: take over navigation
input.addEventListener('gazelle:select', (e) => {
  e.preventDefault();
  router.push(new URL(e.detail.href).pathname);
});

Product feeds

Set a feed URL in your dashboard and Gazelle reads it on a schedule (every 6 hours by default). Two formats are accepted.

Google Shopping XML

The same feed you give Google Merchant Center. g:product_type becomes categories, g:item_group_id groups variants, g:custom_label_0…4 become tags, and g:color, g:size, g:material become searchable attributes.

JSON

An array of products, or an object with a products array, in the product format below.

REST API

Base URL https://api.gazellesearch.com. Send your key in the X-Gazelle-Key header. The public key (pk_) only searches and can be locked to your domains. The secret key (sk_) manages products and settings; keep it on your server.

Search keys are limited to 600 requests a minute. A limited request gets HTTP 429.

Product format

Only id and title are required.

{
  "id": "123",
  "title": "Running Shoe",
  "sku": "RUN-01",
  "description": "Lightweight mesh upper…",
  "shortDescription": "Daily trainer",
  "price": 1999,
  "salePrice": 1499,
  "currency": "USD",
  "brand": "Gazelle",
  "categories": ["Shoes", "Running"],
  "tags": ["sport"],
  "availability": "in stock",
  "rating": 4.6,
  "popularity": 120,
  "image": "https://…/run-01.jpg",
  "url": "https://…/run-01",
  "attributes": { "color": "black" },
  "customFields": { "material": "mesh" },
  "variations": [
    { "id": "123-42", "sku": "RUN-01-42", "price": 1999, "attributes": { "size": "42" } }
  ]
}

How matching works

• Every word has to match. Queries of three or more words fall back to matching at least half of them.
• The word being typed matches as a prefix: “iph” finds iPhone.
• Fuzzy matching allows 1 typo in words of 3–5 letters and 2 in longer words. Words with digits are never fuzzed.
• SKUs are compared without dashes or spaces, and partial SKUs match.
• Prices and stock in the words become filters: “under 50”, “between 20 and 40”, “in stock”, “on sale”.
• When nothing matches, the closest catalog words are searched instead and shown as “Did you mean”.
• Synonyms work both ways. Stop words are dropped before matching.
• Ranking: title, then brand, categories and tags, then attributes and descriptions. Popularity breaks ties.