Home
APIs
Data & Extraction
E-Commerce Natural Language Search Query Parser API

Data & Extraction API

E-Commerce Natural Language Search Query Parser API

Natural language query understanding API that converts buyer search strings into structured SQL/Elasticsearch filters.

POST https://rsflowhub.com/api/v1/ai/search-query-parse

3 credits per call
X-API-Key header
JSON in, JSON out

Try it in the playground API reference

POST /api/v1/ai/search-query-parse

{
    "query": "Samsung 5G phones under \u20b920,000 with 8GB RAM, highest rated first",
    "schema": {
        "brand": {
            "type": "string"
        },
        "network": {
            "type": "string"
        },
        "price": {
            "type": "number"
        },
        "ram": {
            "type": "string"
        },
        "rating": {
            "type": "number"
        }
    },
    "context": {
        "domain": "ecommerce",
        "default_currency": "INR"
    }
}

200 OK response.json

{
    "result": {
        "original_query": "red running shoes under 100 dollars size 10",
        "normalized_query": "red running shoes",
        "intent": "product_search",
        "language": "en",
        "filters": [
            {
                "field": "color",
                "value": "red"
            },
            {
                "field": "category",
                "value": "running shoes"
            },
            {
                "field": "price_max",
                "value": 100
            },
            {
                "field": "size",
                "value": "10"
            }
        ],
        "exclude": [],
        "sort": {
            "field": "relevance",
            "direction": "desc"
        },
        "is_ambiguous": false
    }
}

Definition

What is the E-Commerce Natural Language Search Query Parser API?

E-Commerce Natural Language Search Query Parser API is a REST API on RSFlowHub for web, mobile and AI agent applications. Send a JSON request to POST /api/v1/ai/search-query-parse with your API key; RSFlowHub runs it on a tuned AI model, falls back to a backup provider if needed, and returns a structured JSON result, usually within 1 to 3 seconds.

Category: Data & Extraction
Endpoint: POST /api/v1/ai/search-query-parse
Authentication: X-API-Key header
Price: 3 credits per call
Rate limit: 10 to 120 requests / minute by plan
Typical response: 1 to 3 seconds
Format: JSON, UTF-8

Request parameters

Send these fields as a JSON body. An invalid or missing field returns a 422 error that names the field.

Field	Type	Required	Description
`query`	string	Required	The raw user natural-language search string (Max: 5,000 characters).
`schema`	object	Optional	Optional JSON object mapping field names to types, allowed values, sortability parameters to restrict generated filters.
`context`	object	Optional	Optional JSON object defining business context (e.g. domain, default currency, timezone).

Code examples

Copy, replace rfh_your_api_key with your key and run. Prefer a client library? See the official SDKs.

request.sh

curl -X POST "https://rsflowhub.com/api/v1/ai/search-query-parse" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rfh_your_api_key" \
  -d '{"query":"Samsung 5G phones under \u20b920,000 with 8GB RAM, highest rated first","schema":{"brand":{"type":"string"},"network":{"type":"string"},"price":{"type":"number"},"ram":{"type":"string"},"rating":{"type":"number"}},"context":{"domain":"ecommerce","default_currency":"INR"}}'

client.php

<?php

$client = new \GuzzleHttp\Client();
$response = $client->post('https://rsflowhub.com/api/v1/ai/search-query-parse', [
    'headers' => [
        'Content-Type' => 'application/json',
        'X-API-Key'    => 'rfh_your_api_key',
    ],
    'json' => array (
      'query' => 'Samsung 5G phones under ₹20,000 with 8GB RAM, highest rated first',
      'schema' => 
      array (
        'brand' => 
        array (
          'type' => 'string',
        ),
        'network' => 
        array (
          'type' => 'string',
        ),
        'price' => 
        array (
          'type' => 'number',
        ),
        'ram' => 
        array (
          'type' => 'string',
        ),
        'rating' => 
        array (
          'type' => 'number',
        ),
      ),
      'context' => 
      array (
        'domain' => 'ecommerce',
        'default_currency' => 'INR',
      ),
    ),
]);

echo $response->getBody();

client.js

const response = await fetch('https://rsflowhub.com/api/v1/ai/search-query-parse', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'rfh_your_api_key'
  },
  body: JSON.stringify({"query":"Samsung 5G phones under \u20b920,000 with 8GB RAM, highest rated first","schema":{"brand":{"type":"string"},"network":{"type":"string"},"price":{"type":"number"},"ram":{"type":"string"},"rating":{"type":"number"}},"context":{"domain":"ecommerce","default_currency":"INR"}})
});

const data = await response.json();
console.log(data);

main.py

import requests

url = "https://rsflowhub.com/api/v1/ai/search-query-parse"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "rfh_your_api_key"
}
payload = {"query":"Samsung 5G phones under \u20b920,000 with 8GB RAM, highest rated first","schema":{"brand":{"type":"string"},"network":{"type":"string"},"price":{"type":"number"},"ram":{"type":"string"},"rating":{"type":"number"}},"context":{"domain":"ecommerce","default_currency":"INR"}}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Every RSFlowHub endpoint uses the same envelope, so one parser handles all of them. Failed calls are not charged.

response.json

{
    "success": true,
    "request_id": "req_3f9a2c7e-5b1d-4e8a-9c2f-7d6e1a0b4c8d",
    "data": {
        "result": {
            "original_query": "red running shoes under 100 dollars size 10",
            "normalized_query": "red running shoes",
            "intent": "product_search",
            "language": "en",
            "filters": [
                {
                    "field": "color",
                    "value": "red"
                },
                {
                    "field": "category",
                    "value": "running shoes"
                },
                {
                    "field": "price_max",
                    "value": 100
                },
                {
                    "field": "size",
                    "value": "10"
                }
            ],
            "exclude": [],
            "sort": {
                "field": "relevance",
                "direction": "desc"
            },
            "is_ambiguous": false
        }
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-05T09:30:00Z"
    }
}

error.json

{
    "success": false,
    "request_id": "req_8c1d4e2a-7f3b-4a9c",
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The given data was invalid.",
        "details": {
            "query": [
                "This field is required."
            ]
        }
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-05T09:30:00Z"
    }
}

Envelope fields
Field	Type	Meaning
`success`	boolean	true when the call worked, false on any error.
`request_id`	string	Unique id for this call. Quote it when you contact support.
`data.result`	object	The result of this endpoint (see the example).
`error`	object	Only on failure: code, message and details per field.
`meta`	object	API version and server timestamp.

All error codes: Errors reference

Features

Attribute & Entity Extraction

Extracts brand names, model numbers, color preferences, sizes, and technical specs from raw search text.

Price & Range Normalization

Converts phrases like "under $50", "under ₹20,000", or "budget friendly" into exact numeric min/max price boundaries.

Sort Order & Intent Parsing

Detects buyer sorting intent such as "cheapest first", "highest rated", or "newest arrivals".

Query Cleansing & Typo Correction

Automatically corrects typos and normalizes product categories prior to database querying.

Use cases

How teams use the E-Commerce Natural Language Search Query Parser API in production.

E-Commerce Marketplace

E-Commerce Marketplace Search

Parse buyer search strings like "red Nike sneakers size 10 under $100" into exact product catalog filter queries.

Input: Samsung 5G phones under ₹20,000 with 8GB RAM, highest rated first
Output: {"brand": "Samsung", "network": "5G", "max_price": 20000, "ram": "8GB", "sort_by": "rating_desc"}

Helps shoppers find the right products from natural-language searches.

PropTech

Real Estate & Property Search

Convert search strings like "3 bedroom apartment in downtown Miami with pool under $3k" into DB filters.

Input: 3 bedroom apartment in downtown Miami with pool under $3k
Output: {"bedrooms": 3, "location": "downtown Miami", "max_price": 3000, "amenities": ["pool"]}

Delivers relevant property listings instantly.

TravelTech

Travel & Hotel Booking Engine

Parse natural queries like "5-star beach resort in Bali with free breakfast" into hotel availability API parameters.

Input: 5-star beach resort in Bali with free breakfast
Output: {"rating": 5, "location": "Bali", "property_type": "resort", "amenities": ["beachfront", "free_breakfast"]}

Enhances user discovery experience.

E-Commerce Natural Language Search Query Parser API vs building it yourself

The same job done three ways.

Topic	RSFlowHub API	Raw LLM prompts	Rules / regex
Output	Validated JSON fields	Free text you have to parse	Fixed patterns only
Setup	One POST request, no prompts	Write and maintain prompts and parsing	Write and maintain rule lists
Provider outage	Automatic fallback to a backup model	You build retries and a second vendor	Not applicable
Pricing	3 credits per call, failed calls free	Per token, per vendor	Your own servers and upkeep
Understands context	Yes, AI model	Yes, AI model	No, keywords only

Frequently asked questions

How does the Search Query Parser API handle typos and informal language?

The API utilizes contextual natural language understanding to correct typos, recognize synonyms, and normalize informal terms before generating filter objects.

Can I integrate this with Elasticsearch, Algolia, or SQL databases?

Yes! The API returns standard JSON filter objects that can be directly mapped to SQL WHERE clauses, Elasticsearch queries, or Algolia filters.

How does price normalization work for different currencies?

You can pass a default currency in the context parameter (e.g., USD, EUR, INR) so price ranges are correctly parsed into appropriate numeric thresholds.

How fast is the Search Query Parser API?

Search Query Parser requests usually complete in 1 to 3 seconds, depending on input length and the AI model. Identical repeat requests are served from cache and return faster.

How many credits are deducted per request?

Search Query Parser API calls consume 3 base credits per request.

Start using the E-Commerce Natural Language Search Query Parser API

Free plan with 100 credits/month + 1,000 bonus credits when you sign in before 23 Nov. Test it in the playground first, no code needed.

Get a free API key Try it now