@vepler/safety-types/routes/geography/get-metrics.d.ts

TypeScript type definitions for Vepler Safety Service API

/**
 * Types for /api/geography/get-metrics endpoint
 */
import { CategoryMetrics, CategoryMetricsWithName } from '../crime/get-category-stats';
/**
 * Query parameters for geography metrics
 */
export interface GetMetricsQueryParams {
    /** Geographic codes to query (comma-separated) */
    geographicCodes: string;
    /** Time periods to query (comma-separated) */
    periods?: string;
    /** Start date for date range queries */
    startDate?: string;
    /** End date for date range queries */
    endDate?: string;
    /** Whether to merge areas in results */
    mergeAreas?: boolean;
    /** Whether to include time series data */
    includeTimeSeries?: boolean;
    /** Number of months to include (default: 12) */
    months?: number;
    /** Whether to include percentage change calculations */
    includePercentageChange?: boolean;
    /** Whether to include rich crime score data (percentile, trends, explanatory tags, etc.) */
    includeRichData?: boolean;
    /** Country code (default: 'uk') */
    countryCode?: string;
    /** Crime categories to filter (comma-separated) */
    categories?: string;
}
/**
 * Percentage change data for crime metrics
 */
export interface PercentageChangeData {
    /** Percentage change in crime count */
    crimeCount?: number | null;
    /** Percentage change in crime rate */
    crimeRate?: number | null;
    /** Percentage change in crime score */
    crimeScore?: number | null;
    /** Percentage change in percentile ranking */
    percentile?: number | null;
    /** Percentage change in severity score */
    severityScore?: number | null;
    /** Percentage change in severity score per thousand */
    severityScorePerThousand?: number | null;
}
/**
 * Category-specific percentage changes
 */
export interface CategoryPercentageChange {
    /** Category name */
    category: string;
    /** Month-over-month percentage changes */
    monthOverMonth?: PercentageChangeData;
    /** Year-over-year percentage changes */
    yearOverYear?: PercentageChangeData;
}
/**
 * Overall percentage changes for all metrics
 */
export interface OverallPercentageChanges {
    /** Overall month-over-month changes */
    monthOverMonth?: PercentageChangeData;
    /** Year-over-year changes */
    yearOverYear?: PercentageChangeData;
    /** Per-category percentage changes */
    categories?: CategoryPercentageChange[];
}
/**
 * Time series data point for geography metrics
 */
export interface GeographyTimeSeriesDataPoint {
    /** Period in YYYY-MM format */
    period: string;
    /** Category name */
    category: string;
    /** Number of crimes for this category and period */
    crimeCount: number;
    /** Crime rate per 1000 population for this category and period */
    crimeRate: number;
    /** Crime score (0-100) for this category and period */
    crimeScore: number | null;
    /** Percentile ranking against peer areas (0-100) */
    percentile?: number;
    /** Raw severity score before normalization */
    severityScore?: number;
    /** Severity score normalized per 1000 population */
    severityScorePerThousand?: number;
    /** Trend factor (-1 to 1, negative means improving) */
    trendFactor?: number;
    /** Whether the trend is statistically significant */
    trendSignificance?: boolean;
    /** Confidence interval for the crime score */
    confidenceInterval?: {
        lower: number;
        upper: number;
    };
    /** Explanatory tags describing factors driving the score */
    explanatoryTags?: string[];
    /** Period details for the calculation */
    periodDetails?: {
        start: string;
        end: string;
    };
}
/**
 * Geography metrics response
 */
export interface GetMetricsResponse {
    /** Geographic code of the area */
    geographicCode: string;
    /** Human-readable name of the area */
    name: string;
    /** Population of the area */
    population: number;
    /** Time period for this data */
    period: string;
    /** Total crime count across all categories */
    totalCrimeCount: number;
    /** Total crime rate per 1000 population */
    totalCrimeRate: number;
    /** Total crime score (0-100) */
    totalCrimeScore: number;
    /** Data availability status */
    dataAvailability?: string;
    /** Crime metrics by category */
    categories: CategoryMetricsWithName[];
    /** Time series data if requested */
    timeSeriesData: GeographyTimeSeriesDataPoint[];
    /** Percentage changes compared to previous periods */
    percentageChanges?: OverallPercentageChanges;
}
/**
 * Area metrics response
 * @deprecated Use GetMetricsResponse instead
 */
export interface AreaMetricsResponse {
    /** Geographic code of the area */
    geographicCode: string;
    /** Human-readable name of the area */
    name: string;
    /** Population of the area */
    population: number;
    /** Country code */
    countryCode: string;
    /** Type of geographic entity (e.g., 'lsoa21') */
    geographicEntityType: string;
    /** Crime metrics by category */
    categories: Record<string, CategoryMetrics>;
    /** Time series data if requested */
    timeSeries?: Array<{
        /** Period in YYYY-MM-DD format */
        period: string;
        /** Crime metrics by category for this period */
        categories: Record<string, CategoryMetrics>;
    }>;
}
/**
 * Error response for geography operations
 */
export interface GeographyErrorResponse {
    /** Whether the operation was successful */
    success: false;
    /** Error message */
    error: string;
    /** Detailed validation errors if applicable */
    details?: Array<{
        /** Field that failed validation */
        field: string;
        /** Error message for this field */
        message: string;
    }>;
}