# facetize.io

> AI-powered ecommerce query translation API

## What is facetize.io?

facetize.io provides an API that translates natural language ecommerce queries into structured product filters. Built on top of Shopify's comprehensive product taxonomy, our API converts queries like "Find blue t-shirts under $50" into standardized categories, attributes, values, and price ranges that work seamlessly with any ecommerce platform.

The Shopify product taxonomy is one of the most comprehensive and standardized product classification systems available, covering thousands of product categories and attributes across all retail verticals.

## What Problems Does It Solve?

- **Poor search experiences**: Customers struggle to find products when using vague or conversational language
- **Complex filter mapping**: Converting natural language to your product taxonomy is technically challenging
- **Voice commerce**: Enable natural voice-based product searches
- **Time to market**: Avoid building and maintaining your own NLP infrastructure

## Who Is It For?

- **Finqu and Shopify store owners** - Native compatibility with Shopify's product taxonomy
- **E-commerce platforms** - Works with any platform using standardized product classification
- **Developers** - Building shopping experiences or product recommendation systems
- **Voice assistant integrators** - Enabling natural language product discovery
- **Marketplace builders** - Needing intelligent product filtering with industry-standard taxonomy

## Use Cases

1. **Enhanced Site Search** - Transform "something comfortable for summer" into precise category and attribute filters
2. **Voice Shopping** - Enable customers to search products using natural speech
3. **Smart Recommendations** - Build recommendation engines that understand intent
4. **Inventory Management** - Quickly filter large catalogs using conversational queries
5. **Customer Support Tools** - Help support staff find products faster using natural language

## How It Works

**1. Sign up** for a free account at https://facetize.io

**2. Get your API key** from the dashboard

**3. Send a POST request** to our API:

```bash
curl -X POST https://facetize.io/api/translate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Find blue t-shirts under $50"}'
```

**4. Receive structured data** you can use to filter your product catalog:

```json
{
  "categories": {
    "gid1": { "name": "Apparel", "confidence": 0.95 }
  },
  "attributes": {
    "gid2": {
      "name": "Color",
      "confidence": 0.92,
      "values": {
        "gid3": { "name": "Blue", "confidence": 0.88 }
      }
    },
    "gid4": {
      "name": "Product Type",
      "confidence": 0.89,
      "values": {
        "gid5": { "name": "T-Shirt", "confidence": 0.91 }
      }
    }
  },
  "priceRange": { "max": 50 }
}
```

## Key Features

- **Built on Shopify Taxonomy** - Uses Shopify's industry-standard product classification system
- **High Accuracy** - AI-powered understanding of customer intent
- **Fast Response Times** - Optimized for sub-second responses
- **Confidence Scores** - Know how certain we are about each match
- **Price Range Extraction** - Automatically detects budget constraints
- **Vendor/Brand Recognition** - Identifies specific brands mentioned
- **Product Option Generation** - Generate structured product options from natural language instructions
- **Comprehensive Coverage** - Thousands of product categories and attributes across all retail verticals
- **Platform Agnostic** - Works with Shopify, WooCommerce, Magento, custom platforms, and more
- **RESTful API** - Simple integration with any platform or language
- **MCP Server** - Also available via Model Context Protocol for MCP-compatible clients

## Pricing

**Pay-as-you-go:** $0.01 per API request

- No monthly subscription fees
- No minimum commitments
- Only pay for what you use
- Add credits to your account via Stripe ($5 minimum)
- Volume discounts available for enterprise customers

## Rate Limits

Free tier includes:
- 10 requests per minute
- 100 requests per hour
- 1,000 requests per day

Higher tiers automatically unlock as you use the service more, with limits scaling up to 1,000 requests per minute for established accounts.

## Getting Started

1. **Create an account** at https://facetize.io/signup
2. **Generate an API key** from your dashboard
3. **Make your first request** using the interactive tester in your dashboard
4. **Add credits** to your account when ready for production use
5. **Monitor usage** through the dashboard analytics

## API Endpoints

### POST /api/translate

**Authentication:** Bearer token (API key)

**Request body:**
```json
{
  "query": "your natural language search query",
  "context": "optional context to help disambiguation"
}
```

**Response:** Structured JSON with categories, attributes, values, vendors, and price ranges, each with confidence scores.

### POST /api/generate

**Authentication:** Bearer token (API key)

**Request body:**
```json
{
  "instruction": "create a t-shirt with options for blue, white, lime and sizes s to xl"
}
```

**Response:** Structured JSON with product options, each containing a title, GID (Shopify taxonomy reference), and array of values with their own GIDs.

```json
{
  "options": [
    {
      "title": "Color",
      "gid": "gid://shopify/TaxonomyAttribute/1",
      "values": [
        { "title": "blue", "gid": "gid://shopify/TaxonomyValue/1", "value": "blue" },
        { "title": "lime", "gid": "gid://shopify/TaxonomyValue/7", "value": "lime" }
      ]
    },
    {
      "title": "Size",
      "gid": "gid://shopify/TaxonomyAttribute/2778",
      "values": [
        { "title": "s", "gid": "gid://shopify/TaxonomyValue/2345", "value": "s" },
        { "title": "xl", "gid": "gid://shopify/TaxonomyValue/2348", "value": "xl" }
      ]
    }
  ]
}
```

### MCP Server

Also available via Model Context Protocol at `https://facetize.io/api/mcp` for MCP-compatible clients (e.g., Claude Desktop). See https://facetize.io/mcp-docs for details.

Available MCP tools: `translate`, `generate`

## Support

- **Interactive Documentation**: Available in your dashboard after signup
- **Example Queries**: Test the API directly from your browser
- **Usage Analytics**: Track your API usage and costs in real-time
- **Changelog**: Stay updated with new features at https://facetize.io/changelog

## Privacy & Security

- All API requests are encrypted via HTTPS
- We don't store your query data long-term
- API keys can be regenerated or revoked at any time

## Terms

By using facetize.io, you agree to our terms of service and privacy policy available at:
- Terms: https://facetize.io/terms
- Privacy: https://facetize.io/privacy

## Contact

Questions? Contact us at finqu.com