search api with filters autocomplete

Here’s a practical pattern for building a search API with filters + autocomplete.

Recommended endpoints

1) Search endpoint

GET /search Query params:

• q = full-text query
• filters[...] = structured filters
• sort = optional sort field
• page, limit = pagination

Example:

GET /search?q=iphone&filters[brand]=apple&filters[price_gte]=500&filters[price_lte]=1000&page=1&limit=20

Response:

{
  "data": [
    { "id": 1, "title": "iPhone 15", "brand": "Apple", "price": 899 }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 153
  }
}

---

2) Autocomplete endpoint

GET /search/autocomplete Query params:

• q = partial input
• limit = number of suggestions
• optionally filters[...] if suggestions should respect filters

Example:

GET /search/autocomplete?q=iph&filters[brand]=apple&limit=5

Response:

{
  "suggestions": [
    { "type": "query", "value": "iphone" },
    { "type": "product", "value": "iPhone 15" },
    { "type": "product", "value": "iPhone 15 Pro" }
  ]
}

---

Filter format options

Option A: Flat query params

Good for simple APIs:

/search?q=tv&brand=sony&minPrice=500&maxPrice=2000&category=electronics

Option B: Nested filter object

Better for extensibility:

/search?q=tv&filters[brand]=sony&filters[price][gte]=500&filters[price][lte]=2000

Option C: JSON body for POST search

Useful when filters get complex:

POST /search
Content-Type: application/json

{
  "q": "tv",
  "filters": {
    "brand": ["sony", "lg"],
    "price": { "gte": 500, "lte": 2000 },
    "inStock": true
  },
  "sort": [{ "field": "relevance", "order": "desc" }],
  "page": 1,
  "limit": 20
}

---

Autocomplete best practices

• Trigger after 2–3 characters
• Debounce requests by 150–300ms
• Return results fast: ideally <100ms
• Use prefix matching and/or search index
• Support cancellation of stale requests
• Optionally return:
  • query suggestions
  • product/entity suggestions
  • category suggestions
  • recent/popular searches

---

If you want one API that does both

You can use:

GET /search?q=iph&mode=autocomplete
GET /search?q=iphone&filters[brand]=apple

But in most cases, separate endpoints are cleaner.

---

Backend implementation notes

For good performance:

• Use a search engine like Elasticsearch / OpenSearch / Meilisearch / Typesense
• Index fields needed for:
  • text search
  • filters
  • sorting
  • autocomplete suggestions

If using SQL:

• full-text search for q
• indexed columns for filters
• separate table/materialized view for autocomplete suggestions

---

Example OpenAPI sketch

/search:
  get:
    parameters:
      - name: q
        in: query
        schema: { type: string }
      - name: filters[brand]
        in: query
        schema: { type: string }
      - name: filters[price_gte]
        in: query
        schema: { type: number }
      - name: filters[price_lte]
        in: query
        schema: { type: number }
    responses:
      '200':
        description: Search results

/search/autocomplete:
  get:
    parameters:
      - name: q
        in: query
        schema: { type: string }
      - name: limit
        in: query
        schema: { type: integer, default: 5 }
    responses:
      '200':
        description: Suggestions

If you want, I can also give you:

1. a Node/Express example,
2. a FastAPI example, or
3. a database schema + query design for search with filters and autocomplete.