Search API

Overview

The Search API allows you to:

Search across characters, users, and comments
Filter by entity type
Get paginated search results
Sort results by relevance or date

Endpoints

GET /api/search

Perform a global search across all entities.

Permissions: Public access

Query Parameters:

q (string, required): Search query
type (string, optional): Filter by entity type (characters, users, comments, all)
page (number, default: 1): Page number for pagination
limit (number, default: 10, max: 100): Number of items per page
sortBy (string, default: "relevance"): Sort field (relevance, createdAt, updatedAt)
sortOrder (string, default: "desc"): Sort order (asc, desc)

Example Request:

curl "https://api.nikode.ir/api/search?q=naruto&type=characters&page=1&limit=10"

Example Response:

{
  "success": true,
  "message": "Search completed successfully",
  "data": {
    "query": "naruto",
    "totalResults": 5,
    "results": [
      {
        "type": "character",
        "id": "char_1",
        "name": "Naruto Uzumaki",
        "anime": "Naruto",
        "power": 95,
        "intelligence": 70,
        "speed": 85,
        "strength": 80,
        "image": "https://example.com/naruto.jpg",
        "description": "The main protagonist of Naruto series",
        "abilities": ["Rasengan", "Shadow Clone Jutsu", "Sage Mode"],
        "personality": "Determined and never gives up",
        "birthday": "October 10",
        "height": "180cm",
        "weight": "75kg",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z",
        "relevanceScore": 0.95
      },
      {
        "type": "comment",
        "id": "comment_1",
        "characterId": "char_1",
        "userId": "user_1",
        "content": "Naruto is my favorite character!",
        "rating": 5,
        "status": "approved",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z",
        "relevanceScore": 0.85
      }
    ],
    "facets": {
      "types": {
        "character": 3,
        "comment": 2,
        "user": 0
      },
      "anime": {
        "Naruto": 3,
        "Dragon Ball": 1,
        "One Piece": 1
      }
    }
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

GETTest GET /api/search

Perform a global search across all entities

Query Parameters

q *

type

page

limit

sortBy

sortOrder

Search Features

Search Query Types

The search API supports various query types:

Text Search: Search by name, description, content
```
q=naruto
q="dragon ball"
```

Entity-Specific Search: Filter by entity type

type=characters
type=users
type=comments
type=all

Combined Search: Use multiple parameters

q=goku&type=characters&sortBy=power&sortOrder=desc

Search Results

Each search result includes:

type: The entity type (character, user, comment)
id: Unique identifier
relevanceScore: How well the result matches the query (0-1)
Entity-specific fields: All fields from the original entity

Faceted Search

Search results include faceted information:

types: Count of results by entity type
anime: Count of character results by anime series
roles: Count of user results by role
status: Count of comment results by status

Data Models

Search Result

interface SearchResult {
  type: "character" | "user" | "comment";
  id: string;
  relevanceScore: number;
  // ... entity-specific fields
}

Search Response

interface SearchResponse {
  query: string;
  totalResults: number;
  results: SearchResult[];
  facets: {
    types: Record<string, number>;
    anime?: Record<string, number>;
    roles?: Record<string, number>;
    status?: Record<string, number>;
  };
}

Search Examples

Character Search

# Search for characters by name
curl "https://api.nikode.ir/api/search?q=goku&type=characters"

# Search for characters by anime
curl "https://api.nikode.ir/api/search?q=dragon&type=characters"

# Search for powerful characters
curl "https://api.nikode.ir/api/search?q=power&type=characters&sortBy=power&sortOrder=desc"

User Search

# Search for users by username
curl "https://api.nikode.ir/api/search?q=admin&type=users"

# Search for users by role
curl "https://api.nikode.ir/api/search?q=moderator&type=users"

Comment Search

# Search for comments by content
curl "https://api.nikode.ir/api/search?q=amazing&type=comments"

# Search for approved comments
curl "https://api.nikode.ir/api/search?q=great&type=comments&status=approved"

Global Search

# Search across all entities
curl "https://api.nikode.ir/api/search?q=naruto&type=all"

# Search with pagination
curl "https://api.nikode.ir/api/search?q=anime&page=2&limit=20"

Error Codes

Code	Status	Description
`NOT_FOUND`	404	Search query not found
`VALIDATION_ERROR`	400	Invalid search parameters
`INTERNAL_ERROR`	500	Server error

Rate Limits

User: 100 requests per hour
Moderator: 500 requests per hour
Admin: 1000 requests per hour

Examples

JavaScript/Node.js

// Search for characters
const response = await fetch("/api/search?q=goku&type=characters");
const searchResults = await response.json();

// Global search
const globalSearch = await fetch(
  "/api/search?q=anime&type=all&page=1&limit=10"
);
const results = await globalSearch.json();

Python

import requests

# Search for characters
response = requests.get(
    'https://api.nikode.ir/api/search',
    params={'q': 'goku', 'type': 'characters'}
)
search_results = response.json()

# Global search
global_search = requests.get(
    'https://api.nikode.ir/api/search',
    params={'q': 'anime', 'type': 'all', 'page': 1, 'limit': 10}
)
results = global_search.json()

cURL

# Search for characters
curl "https://api.nikode.ir/api/search?q=goku&type=characters"

# Search for users
curl "https://api.nikode.ir/api/search?q=admin&type=users"

# Search for comments
curl "https://api.nikode.ir/api/search?q=amazing&type=comments"

# Global search with pagination
curl "https://api.nikode.ir/api/search?q=anime&type=all&page=1&limit=10&sortBy=relevance&sortOrder=desc"

Search Tips

Use quotes for exact phrases: q="dragon ball"
Combine with entity filters: q=naruto&type=characters
Use pagination for large results: page=2&limit=20
Sort by relevance: sortBy=relevance&sortOrder=desc
Check facets for insights: Look at the facets object in responses

Performance Notes

Search results are cached for 5 minutes
Complex queries may take longer to process
Use specific entity types when possible for better performance
Pagination is recommended for large result sets

Search API

On this page