@vepler/schools-types/api/endpoints/metrics-geographic.d.ts

TypeScript type definitions for Vepler Schools Service

/**
 * Geographic Metrics Endpoint Types
 *
 * Type definitions for the /metrics/geographic API endpoint.
 * This file contains both request and response types.
 */
import { CohortType } from '../../models/metric';
import { ObjectApiResponse } from '../common';
export type MetricProfile = 'ks2' | 'ks4' | 'ks5' | 'pupil' | 'finance' | 'ofsted';
/**
 * Valid geographic types that can be used for aggregation
 */
export type GeographicType = 'lsoa' | 'ward' | 'localAuthority' | 'region' | 'country';
/**
 * Request body for the /metrics/geographic POST endpoint
 */
export interface MetricsGeographicRequestBody {
    /**
     * Array of specific metric codes to query
     * @description Mutually exclusive with profile
     * @example ["PTRWM_EXP", "ATT8SCR"]
     */
    metricCodes?: string[];
    /**
     * Pre-defined profile(s) of metrics to return
     * @enum ["ks2", "ks4", "ks5", "pupil", "finance", "ofsted"]
     * @description Mutually exclusive with metricCodes. Can be a comma-separated list of profiles.
     * @example "ks2,ks4,pupil"
     */
    profile?: string;
    /**
     * Geographic area specification
     * @required
     */
    geography: {
        /**
         * Array of geographic codes (e.g., LSOA codes, Local Authority codes)
         * @required
         * @example ["E09000012", "E09000033"]
         */
        codes: string[];
        /**
         * Type of geographic entity specified by the codes
         * @required
         */
        type: GeographicType;
    };
    /**
     * Academic year ID (e.g., "GB_2022-2023")
     * @description If not provided, metrics from the latest academic year will be returned
     */
    academicYearId?: string;
    /**
     * Student cohort type for filtering metrics
     * @default "all"
     */
    cohortType?: CohortType;
    /**
     * Whether to include hierarchical results
     * @description This will include child geographies in the response
     * @default false
     */
    hierarchicalResults?: boolean;
    /**
     * Levels of geographic hierarchy to include in hierarchical results
     * @description Only required when hierarchicalResults is true
     * @example ["region", "localAuthority", "lsoa"]
     */
    aggregationLevels?: GeographicType[];
    /**
     * Include metric definitions metadata in response
     * @default false
     */
    includeMetadata?: boolean;
    /**
     * Maximum number of geographic areas to return
     * @default 50
     * @minimum 1
     * @maximum 100
     */
    limit?: number;
    /**
     * Number of geographic areas to skip (for pagination)
     * @default 0
     * @minimum 0
     */
    offset?: number;
}
/**
 * Aggregated metric data item for a geographic area
 */
export interface GeographicMetricItem {
    /**
     * Metric code identifier
     */
    metricCode: string;
    /**
     * Metric description
     */
    description?: string;
    /**
     * Metric category
     */
    category?: string;
    /**
     * Metric data type
     */
    dataType?: string;
    /**
     * Average value of the metric across schools in this geographic area
     */
    average: number;
    /**
     * Median value of the metric across schools in this geographic area
     */
    median?: number;
    /**
     * Number of schools with this metric in the geographic area
     */
    count: number;
    /**
     * Minimum value of the metric across schools in this geographic area
     */
    min?: number;
    /**
     * Maximum value of the metric across schools in this geographic area
     */
    max?: number;
    /**
     * Standard deviation of the metric across schools in this geographic area
     */
    stdDev?: number;
    /**
     * Optional metric metadata (included when includeMetadata=true)
     */
    metadata?: {
        category: string;
        subcategory: string;
        dataType: string;
        description: string;
        nationalAverage?: string;
        expectedRange?: {
            min: number;
            max: number;
        };
        [key: string]: any;
    };
}
/**
 * Geographic area with aggregated metrics
 */
export interface GeographicAreaMetrics {
    /**
     * Geographic code of the area
     */
    geographyCode: string;
    /**
     * Human-readable name of the geographic area
     */
    geographyName: string;
    /**
     * Type of geographic entity
     */
    geographyType: GeographicType;
    /**
     * Number of schools in this geographic area
     */
    schoolCount: number;
    /**
     * Aggregated metrics for this geographic area
     */
    metrics: GeographicMetricItem[];
    /**
     * Optional child geographic areas with their metrics
     * Only included when hierarchicalResults=true
     */
    children?: GeographicAreaMetrics[];
}
/**
 * Options for querying aggregated metrics by geographic area
 */
export interface GeographicMetricsQueryOptions {
    /**
     * Array of specific metric codes to query
     * Mutually exclusive with profile
     */
    metricCodes?: string[];
    /**
     * Pre-defined profile(s) of metrics to return
     * Mutually exclusive with metricCodes
     * Can be a single profile or an array of profiles
     */
    profile?: MetricProfile | MetricProfile[];
    /**
     * Geographic area specification
     */
    geography: {
        /**
         * Array of geographic codes (e.g., LSOA codes, Local Authority codes)
         */
        codes: string[];
        /**
         * Type of geographic entity specified by the codes
         */
        type: GeographicType;
    };
    /**
     * Academic year ID (e.g., "GB_2022-2023")
     * @optional If not provided, metrics from the latest academic year will be returned automatically
     */
    academicYearId?: string;
    /**
     * Student cohort type for filtering metrics
     * @default 'all'
     */
    cohortType?: CohortType;
    /**
     * Whether to include hierarchical results
     * This will include child geographies in the response
     * @default false
     */
    hierarchicalResults?: boolean;
    /**
     * Levels of geographic hierarchy to include in hierarchical results
     * Only applicable when hierarchicalResults is true
     * @example ['region', 'localAuthority', 'lsoa']
     */
    aggregationLevels?: GeographicType[];
    /**
     * Include metric definitions metadata in response
     * @default false
     */
    includeMetadata?: boolean;
    /**
     * Maximum number of geographic areas to return
     * @default 50
     */
    limit?: number;
    /**
     * Number of geographic areas to skip (for pagination)
     * @default 0
     */
    offset?: number;
}
/**
 * Pagination metadata for responses
 */
export interface PaginationMetadata {
    /**
     * Total number of results available
     */
    total: number;
    /**
     * Number of results per page
     */
    limit: number;
    /**
     * Number of results skipped
     */
    offset: number;
    /**
     * Whether there are more results available
     */
    hasMore: boolean;
}
/**
 * Response data structure for geographic metrics endpoint
 */
export interface MetricsGeographicResponseData {
    /**
     * Array of geographic areas with their aggregated metrics
     */
    areas: GeographicAreaMetrics[];
    /**
     * Pagination metadata for the response
     */
    pagination?: PaginationMetadata;
}
/**
 * Complete response for the /metrics/geographic POST endpoint
 * This returns an object with an array of areas, guaranteed to have empty arrays in error cases
 */
export type MetricsGeographicResponse = ObjectApiResponse<MetricsGeographicResponseData>;