1. Get Suggestions API
API Endpoint:
GET /api/suggestions
Description:
This is the primary API endpoint that handles user input and returns a list of suggestions based on the query typed by the user. It performs the search for matching or relevant items in the database or search index and returns the suggestions in real-time.
Request Parameters:
query(string, required): The partial search term that the user is typing (e.g., “New Y” when the user types it in the search bar).limit(integer, optional, default: 10): The maximum number of suggestions to return. This is useful for limiting the size of the result set.user_id(string, optional): A unique user identifier to provide personalized suggestions based on the user’s previous search history or preferences.
Response:
suggestions(array of strings): A list of suggestion strings that match the typed query, e.g.,["New York", "New Year", "New Zealand"].status(string): A status message indicating whether the request was successful (e.g.,OK).error(string, optional): Any error messages or descriptions in case the query failed.
Example Request:
Example Response:
2. Get Popular Queries API
API Endpoint:
GET /api/popular-queries
Description:
This API is used to fetch a list of popular search queries that users are frequently searching for. These popular queries can be used as suggestions to show the user trending or frequently searched terms, which could be pre-defined or dynamically fetched.
Request Parameters:
limit(integer, optional, default: 10): The maximum number of popular queries to return.
Response:
popular_queries(array of strings): A list of popular search queries, such as["New York", "weather", "restaurants near me"].status(string): A status message indicating whether the request was successful.
Example Request:
Example Response:
3. Get Personalized Suggestions API
API Endpoint:
GET /api/personalized-suggestions
Description:
This API is used to return personalized suggestions based on the user’s search history, preferences, and interactions. By providing a user_id or session_token, the system can fetch suggestions that are tailored to the individual user.
Request Parameters:
query(string, required): The partial search query typed by the user.user_id(string, required): A unique identifier for the user to fetch personalized suggestions.limit(integer, optional, default: 10): The maximum number of personalized suggestions to return.
Response:
personalized_suggestions(array of strings): A list of suggestions based on the user’s search history or preferences.status(string): A status message indicating whether the request was successful.
Example Request:
Example Response:
4. Save Search History API
API Endpoint:
POST /api/save-search-history
Description:
This API saves the user’s search history to enable better personalization of future suggestions. It tracks the terms a user has searched for, which can be used for improving typeahead suggestions and personalization.
Request Body:
user_id(string, required): A unique identifier for the user.query(string, required): The query that the user just searched for.timestamp(string, optional): The timestamp when the query was made.
Response:
status(string): A status message indicating whether the search history was successfully saved.
Example Request:
Example Response:
5. Clear Search History API
API Endpoint:
POST /api/clear-search-history
Description:
This API is used to clear the user’s search history. This could be useful for scenarios where a user wants to delete their search history for privacy reasons or for the system to forget old queries.
Request Body:
user_id(string, required): A unique identifier for the user.
Response:
status(string): A status message indicating whether the search history was successfully cleared.
Example Request:
Example Response:
6. Health Check API (for System Monitoring)
API Endpoint:
GET /api/health
Description:
This API is useful for monitoring the health of the Typeahead Suggestion system, ensuring that all components (e.g., database, cache, search index) are operational.
Response:
status(string): A status message indicating the health of the system (e.g.,OK,ERROR).components(object): Status for different components (e.g., database, cache, etc.), showing whether they are operational.
Example Request:
Example Response:
7. Bulk Suggestions API (Optional)
API Endpoint:
POST /api/bulk-suggestions
Description:
This API handles multiple suggestions requests in bulk, allowing the system to process many queries at once. This is useful for optimizing the performance of the system when multiple suggestions are needed at the same time, for instance, during batch processing or bulk analytics.
Request Body:
queries(array of strings, required): A list of partial search queries for which suggestions are needed.
Response:
status(string): A status message indicating whether the request was successful.results(array of arrays of strings): A list of arrays, where each array contains the suggestions for the corresponding query.
Example Request:
Example Response:
