@vepler/schools-types/api/endpoints/search.d.ts

TypeScript type definitions for Vepler Schools Service

/**
 * School Search Endpoint Types
 *
 * Type definitions for the search-related API endpoints.
 */
import { ObjectApiResponse } from '../common';
import { ISchool } from '../../models/school';
/**
 * Input parameters for the /search/schools GET endpoint
 */
export interface SchoolSearchQueryParams {
    /**
     * Search term to find schools
     * @required
     */
    query: string;
    /**
     * Maximum number of results to return
     * @default 10
     * @minimum 1
     * @maximum 100
     */
    limit?: number;
    /**
     * School status to filter by
     * @default "open"
     * @enum ["open", "closed", "pending_closure"]
     */
    status?: 'open' | 'closed' | 'pending_closure';
    /**
     * Page number for pagination
     * @default 1
     * @minimum 1
     */
    page?: number;
    /**
     * Filter by school type
     * @enum ["nursery", "primary", "secondary", "all-through", "sixth-form", "special", "independent", "academy", "other"]
     */
    type?: string;
    /**
     * Filter by Ofsted rating
     * @enum ["outstanding", "good", "satisfactory", "inadequate"]
     */
    rating?: string;
}
/**
 * Response data format for the /search/schools GET endpoint
 */
export interface SchoolSearchResponseData {
    /**
     * List of schools matching the search query
     */
    schools: ISchool[];
    /**
     * Total number of matching schools
     */
    total: number;
    /**
     * Time taken for the search in milliseconds
     */
    timeTaken: number;
}
/**
 * Complete response for the /search/schools GET endpoint
 * This returns an object with an array of schools, guaranteed to have an empty array in error cases
 */
export interface SchoolSearchResponse extends ObjectApiResponse<SchoolSearchResponseData> {
}
/**
 * Input parameters for the /search/schools/autocomplete GET endpoint
 */
export interface SchoolAutocompleteQueryParams {
    /**
     * Prefix to autocomplete for school names
     * @required
     */
    prefix: string;
    /**
     * Maximum number of autocomplete suggestions to return
     * @default 10
     * @minimum 1
     * @maximum 50
     */
    limit?: number;
    /**
     * School status to filter by
     * @default "open"
     * @enum ["open", "closed", "pending_closure"]
     */
    status?: 'open' | 'closed' | 'pending_closure';
    /**
     * Filter by school type
     * @enum ["nursery", "primary", "secondary", "all-through", "sixth-form", "special", "independent", "academy", "other"]
     */
    type?: string;
}
/**
 * School suggestion item returned by autocomplete
 */
export interface SchoolSuggestion {
    /**
     * School ID
     */
    id: number;
    /**
     * School name
     */
    name: string;
    /**
     * SEO-friendly URL slug
     */
    slug: string;
    /**
     * Unique Reference Number
     */
    URN: number;
    /**
     * School type
     */
    type: string;
    /**
     * School postcode
     */
    postcode?: string;
    /**
     * Local authority
     */
    authority?: string;
}
/**
 * Response data format for the /search/schools/autocomplete GET endpoint
 */
export interface SchoolAutocompleteResponseData {
    /**
     * List of school name suggestions
     */
    suggestions: SchoolSuggestion[];
    /**
     * Total number of matching suggestions
     */
    total: number;
    /**
     * Time taken for the autocomplete in milliseconds
     */
    timeTaken: number;
}
/**
 * Complete response for the /search/schools/autocomplete GET endpoint
 * This returns an object with an array of suggestions, guaranteed to have an empty array in error cases
 */
export interface SchoolAutocompleteResponse extends ObjectApiResponse<SchoolAutocompleteResponseData> {
}