Search API

Search API

The Search API provides intelligent search capabilities with AI-powered recommendations, faceted filtering, autocomplete, and multilingual support optimized for the Egyptian market.

Base URL: https://api.osus.ai/v1/search

Search Features

AI-Powered Search

Natural language understanding and semantic search

Multilingual

Arabic, English, and French language support

Advanced Filtering

Faceted search with dynamic filter options

Smart Recommendations

Personalized product recommendations

Search Best Practices
  • Use Arabic terms for better local search results
  • Include category filters to narrow down results
  • Implement autocomplete for better user experience
  • Track search queries for analytics and optimization

Search Products

Perform intelligent product search with various filtering and sorting options.

GET /search

Query Parameters

Parameter Type Description Example
q string Search query (required) أريكة مودرن
lang string Search language: ar, en, fr ar
category string Category filter furniture
brands string[] Brand filters (comma-separated) ikea,home-center
minPrice number Minimum price filter 100
maxPrice number Maximum price filter 5000
colors string[] Color filters أبيض,أسود
materials string[] Material filters خشب,معدن
inStock boolean In stock only true
has3D boolean Has 3D model true
hasAR boolean Has AR support true
sortBy string Sort field: relevance, price, rating, newest relevance
sortOrder string Sort order: asc, desc desc
page integer Page number 1
limit integer Results per page (max: 100) 20

Example Request

curl -X GET 'https://api.osus.ai/v1/search?q=أريكة%20مودرن&category=furniture&minPrice=1000&maxPrice=5000&colors=أبيض,أزرق&sortBy=relevance&limit=20' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept-Language: ar"

Response

{
  "success": true,
  "data": {
    "query": "أريكة مودرن",
    "normalizedQuery": "اريكة مودرن",
    "language": "ar",
    "results": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": {
          "ar": "أريكة مودرن ثلاثية",
          "en": "Modern 3-Seat Sofa"
        },
        "description": {
          "ar": "أريكة مودرن بتصميم عصري وخامات عالية الجودة",
          "en": "Modern sofa with contemporary design and high-quality materials"
        },
        "price": 2500,
        "salePrice": 2000,
        "currency": "EGP",
        "brand": "IKEA",
        "category": "furniture",
        "image": "https://cdn.osus.ai/products/sofa-001-main.jpg",
        "rating": 4.5,
        "reviewCount": 127,
        "inStock": true,
        "has3D": true,
        "hasAR": true,
        "relevanceScore": 0.95,
        "highlights": {
          "name": "أريكة مودرن ثلاثية",
          "description": "أريكة مودرن بتصميم عصري..."
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 145,
      "totalPages": 8,
      "hasNext": true,
      "hasPrev": false
    },
    "facets": {
      "categories": [
        {
          "key": "furniture",
          "name": "أثاث",
          "count": 89
        },
        {
          "key": "decor",
          "name": "ديكور",
          "count": 34
        }
      ],
      "brands": [
        {
          "key": "ikea",
          "name": "IKEA",
          "count": 45
        },
        {
          "key": "home-center",
          "name": "Home Center",
          "count": 32
        }
      ],
      "colors": [
        {
          "key": "أبيض",
          "name": "أبيض",
          "count": 28,
          "hex": "#ffffff"
        },
        {
          "key": "أزرق",
          "name": "أزرق", 
          "count": 22,
          "hex": "#0066cc"
        }
      ],
      "priceRanges": [
        {
          "min": 0,
          "max": 1000,
          "count": 23
        },
        {
          "min": 1000,
          "max": 3000,
          "count": 67
        },
        {
          "min": 3000,
          "max": 5000,
          "count": 41
        }
      ]
    },
    "searchMeta": {
      "searchTime": 0.045,
      "totalResults": 145,
      "correctedQuery": null,
      "suggestions": [
        "أريكة كلاسيك",
        "أريكة جلد",
        "أريكة قماش"
      ]
    }
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "requestId": "req_123456"
}

Search Autocomplete

Get real-time search suggestions as users type.

GET /search/autocomplete

Query Parameters

Parameter Type Description
q string Partial search query (min 2 characters)
lang string Language preference: ar, en, fr
category string Limit suggestions to category
limit integer Number of suggestions (max: 10)

Example Request

curl -X GET 'https://api.osus.ai/v1/search/autocomplete?q=أري&lang=ar&limit=5' \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "query": "أري",
    "suggestions": [
      {
        "text": "أريكة",
        "type": "term",
        "category": "furniture",
        "popularity": 0.85
      },
      {
        "text": "أريكة مودرن",
        "type": "phrase",
        "category": "furniture",
        "popularity": 0.72
      },
      {
        "text": "أريكة جلد",
        "type": "phrase", 
        "category": "furniture",
        "popularity": 0.68
      },
      {
        "text": "أريكة قماش",
        "type": "phrase",
        "category": "furniture", 
        "popularity": 0.61
      },
      {
        "text": "أريكة سرير",
        "type": "phrase",
        "category": "furniture",
        "popularity": 0.54
      }
    ],
    "productSuggestions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "أريكة مودرن ثلاثية",
        "image": "https://cdn.osus.ai/products/sofa-001-thumb.jpg",
        "price": 2500
      }
    ]
  }
}

Product Recommendations

Get personalized product recommendations based on user behavior and preferences.

GET /recommendations

Get personalized recommendations

GET /recommendations/similar/{productId}

Get similar products

GET /recommendations/complementary/{productId}

Get complementary products

Personalized Recommendations

Parameter Type Description
type string Recommendation type: trending, popular, personalized
category string Limit to specific category
limit integer Number of recommendations (max: 50)
excludeViewed boolean Exclude previously viewed products

Example Request

curl -X GET 'https://api.osus.ai/v1/recommendations?type=personalized&category=furniture&limit=10&excludeViewed=true' \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": {
          "ar": "أريكة مودرن ثلاثية",
          "en": "Modern 3-Seat Sofa"
        },
        "price": 2500,
        "salePrice": 2000,
        "image": "https://cdn.osus.ai/products/sofa-001-main.jpg",
        "rating": 4.5,
        "inStock": true,
        "recommendationScore": 0.89,
        "reason": {
          "type": "similar_purchases",
          "description": "مشتريات مشابهة لعملاء آخرين"
        }
      }
    ],
    "algorithm": "collaborative_filtering",
    "userSegment": "furniture_enthusiast",
    "confidence": 0.87
  }
}

Multilingual Search

Search across Arabic, English, and French content with language detection.

Language Support
Arabic (العربية)
  • Full text analysis
  • Stemming & normalization
  • Synonym expansion
  • Dialect recognition
English
  • Natural language processing
  • Semantic search
  • Fuzzy matching
  • Intent recognition
French (Français)
  • Basic text search
  • Accent handling
  • Product name matching
  • Brand recognition

Language Detection Example

curl -X GET 'https://api.osus.ai/v1/search?q=modern sofa blue' \
  -H "Authorization: Bearer YOUR_API_KEY"

Response with Language Detection

{
  "success": true,
  "data": {
    "query": "modern sofa blue",
    "detectedLanguage": "en",
    "translatedQuery": "أريكة مودرن أزرق",
    "results": [...],
    "searchMeta": {
      "languageConfidence": 0.95,
      "crossLanguageMatches": true
    }
  }
}

Search Analytics

Track search performance and user behavior for optimization.

POST /search/analytics/track

Track Search Event

curl -X POST https://api.osus.ai/v1/search/analytics/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "search_performed",
    "searchQuery": "أريكة مودرن",
    "searchResults": 145,
    "clickedResult": {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "position": 1,
      "clickTime": 2.5
    },
    "filters": {
      "category": "furniture",
      "priceRange": "1000-5000"
    },
    "sessionId": "session-123",
    "timestamp": "2025-01-15T10:30:00Z"
  }'

Error Codes

HTTP Status Error Code Description
400 INVALID_SEARCH_QUERY Search query is invalid or too short
400 INVALID_FILTER_PARAMS One or more filter parameters are invalid
400 INVALID_SORT_FIELD Specified sort field is not supported
429 SEARCH_RATE_LIMIT_EXCEEDED Too many search requests per minute
500 SEARCH_SERVICE_UNAVAILABLE Search service temporarily unavailable
503 SEARCH_INDEX_UPDATING Search index is being updated