supafolio-api-docs/api-comparison-guide.md

API Comparison Guide: TypeSense vs Supafolio

Overview Comparison

Feature	TypeSense	Supafolio
Type	Open-source search engine	Proprietary book metadata service
Cost Model	Infrastructure costs only	Per-record/usage pricing
Hosting	Self-hosted required	Fully managed service
Data Format	JSON/JSONL	ONIX + JSON
Performance	Millisecond responses	Variable response times
Scalability	RAM-limited	Cloud-based scaling
Setup Complexity	High (devops required)	Low (plug-and-play)
Privacy	Full data control	Vendor-managed data
Updates	Manual version upgrades	Automatic service updates

Feature-by-Feature Comparison

Search & Discovery

Feature	TypeSense	Supafolio
Text Search	Configurable typo tolerance	Industry-optimized ranking
Faceted Search	Real-time faceting	Pre-configured filters
Autocomplete	Prefix/infix search	Predictive search API
Bulk Operations	Document import/export	Multi-ISBN lookup
Vector Search	Built-in semantic search	Not available
Geo Search	Location-based queries	Geographic search

Data Management

Feature	TypeSense	Supafolio
Schema Control	Custom field definitions	ONIX-based structure
Data Import	JSONL, CSV, JSON import	ONIX file upload
Real-time Updates	Manual reindexing	Automatic daily sync
Validation	Schema validation	ONIX compliance
Data Enrichment	Manual enrichment	Built-in metadata features

Publishing Industry

Feature	TypeSense	Supafolio
Industry Focus	General-purpose	Book publishing specialized
Standards Support	None	ONIX 2.1/3.0 native
Business Rules	Custom implementation	Built-in pricing/rules
Retailer Integration	Manual setup	Pre-configured retailers
Multi-currency	Custom implementation	Built-in currency support
SEO Features	Manual optimization	Built-in SEO overrides

Use Case Recommendations

Choose TypeSense When:

✅ Large Datasets (>100,000 books)
✅ High Search Volume (>1,000 queries/day)
✅ Custom Ranking Required
✅ Real-time Search Needed (<100ms response)
✅ Data Privacy Concerns
✅ Cost Predictability Important
✅ Technical Team Available
✅ Custom Schema Requirements

Choose Supafolio When:

✅ Small Publishers (<10,000 books)
✅ Limited Technical Resources
✅ Industry-Specific Features Needed
✅ Quick Setup Required
✅ Managed Service Preference
✅ ONIX Data Integration Required
✅ SEO/WCMS Integration Priority
✅ Minimal DevOps Overhead

Implementation Comparison

Setup Complexity

TypeSense Setup

# 1. Install TypeSense
curl -O- https://dl.typesense.org/gpu-server/linux-amd64.tar.gz

# 2. Extract and start server
tar -xvf typesense-server-linux-amd64.tar.gz
cd typesense-server-linux-amd64
./typesense-server --data-dir /path/to/data --api-key=your-key --listen-port=8108

# 3. Import book data
./typesense-server import-books.jsonl

# 4. Configure plugin (WordPress)
define('TYPESENSE_API', true);
// Set typesense_api_key, typesense_host, typesense_catalog in WordPress admin

Supafolio Setup

# 1. Install plugin (WordPress)
wp plugin install supapress

# 2. Configure API key (WordPress admin)
# Settings → Supapress → API Key: your-credential-here

# 3. Plugin is ready

Migration Considerations

Data Structure Mapping

TypeSense Field	Supafolio Field	Notes
title	title	Direct mapping
authors[].contributor.name	contributors[].contributor.name	Array to array
publicationDate	date.date	Timestamp to date object
prices.USD.amount	prices[].amount where locale=USD	Object to array
categories	categories[].category.name	Array to array mapping
isbn13	isbn13	Direct mapping

Response Format Transformation

TypeSense → Supafolio Mapping

function supapress_map_search_ts_data($results) {
    $result = [];
    foreach ($results["hits"] as $item) {
        if (!isset($item['document'])) {
            continue;
        }
        $result[] = (object) $item['document'];
    }
    
    return (object) [
        "search" => $result
    ];
}

Performance Comparison

Response Time Analysis

Operation	TypeSense	Supafolio
Simple Search	5-50ms	200-2000ms
Complex Filter	10-100ms	500-3000ms
Faceted Search	20-150ms	800-1500ms
Bulk Lookup	50-200ms	1000-5000ms
Autocomplete	2-20ms	100-500ms

Throughput Analysis

Metric	TypeSense	Supafolio
Concurrent Users	10,000+	100-1,000+
Queries/Second	1,000+	100-500+
Document Size	1-2MB RAM per book	N/A
Storage Efficiency	RAM-based compression	Cloud-based optimization

Cost Analysis

TypeSense Cost Breakdown

Infrastructure:
  - Server: $50-200/month (depends on specs)
  - RAM: 64GB @ $800 = $51,200
  - Bandwidth: 100GB @ $50 = $6,000
  - DevOps: 0.25 FTE @ $80,000 = $20,000
Total Monthly: ~$77,200

Scaling:
  - Additional nodes: $50-200 each
  - Load balancer: $20-50/month
Total at 1M docs: ~$100,000/month initial + ~$20,000/month scaling

Supafolio Cost Structure

Per-Record Pricing:
  - <10,000 books: Custom pricing
  - 10,000-50,000: Standard tier pricing
  - 50,000-100,000: Enterprise tier pricing
  - 100,000+: Custom enterprise pricing

Estimated Monthly:
  - 25,000 books: ~$2,000-5,000/month
  - 100,000 books: ~$8,000-15,000/month

Decision Matrix

Quick Selection Guide

Factor	Weight	Questions to Ask
Dataset Size	30%	How many books in catalog?
Search Volume	25%	What's your daily query load?
Response Time Requirement	20%	What's your acceptable search speed?
Technical Team	15%	Who will maintain the system?
Budget	20%	What's your monthly budget?
Privacy Needs	10%	Any data compliance requirements?

Scoring Guide:

• 0-25 points: Supafolio recommended
• 26-50 points: Hybrid approach considered
• 51-75 points: TypeSense recommended
• 76-100 points: TypeSense strongly recommended

---

Generated: 2026-01-24
TypeSense Version: v29.0
Supafolio Version: v2.26.2