@vepler/area-reference-types/routes/h3/aggregations.d.ts

TypeScript type definitions for Vepler Area Reference API

/**
 * H3 Aggregations API Types
 */
/**
 * Location input - either coordinates or H3 index
 */
export interface H3LocationInput {
    /**
     * Geographic coordinates
     */
    coordinates?: {
        lat: number;
        lng: number;
    };
    /**
     * H3 cell index
     */
    h3Index?: string;
    /**
     * Optional identifier for tracking in response
     */
    id?: string;
}
/**
 * Request body for getting H3 aggregations
 */
export interface GetH3AggregationsRequest {
    /**
     * Array of locations to process (max 100)
     */
    locations: H3LocationInput[];
    /**
     * H3 resolution level (0-15, default: 9)
     */
    resolution?: number;
    /**
     * Components to include in response
     * Default: ['relationships', 'coverage', 'metrics']
     */
    components?: Array<'relationships' | 'coverage' | 'metrics'>;
    /**
     * Force refresh of cached data
     */
    forceRefresh?: boolean;
    /**
     * Specific coverage types to refresh (only if forceRefresh is true)
     */
    refreshCoverageTypes?: string[];
}
/**
 * Geographic relationship data
 */
export interface H3Relationship {
    type: string;
    value: string;
    code: string;
    name: string;
}
/**
 * Environmental coverage data
 */
export interface H3Coverage {
    [coverageType: string]: {
        value: number;
        label?: string;
        metadata?: Record<string, any>;
    };
}
/**
 * Aggregated metrics data
 * Metrics are grouped by category (e.g., connectivity, crime, floodRisk)
 */
export interface H3Metrics {
    [category: string]: {
        [metricKey: string]: {
            value: number;
            unit?: string;
            source?: string;
            lastUpdated?: string;
        };
    };
}
/**
 * Individual H3 aggregation result
 */
export interface H3AggregationResult {
    /**
     * H3 cell index
     */
    h3Index: string;
    /**
     * Center coordinates of the H3 cell
     */
    coordinates: {
        lat: number;
        lng: number;
    };
    /**
     * Optional identifier from request
     */
    id?: string;
    /**
     * Geographic relationships
     */
    relationships?: H3Relationship[];
    /**
     * Environmental coverage data
     */
    coverage?: H3Coverage;
    /**
     * Aggregated metrics
     */
    metrics?: H3Metrics;
    /**
     * Last update timestamp
     */
    lastUpdated: string;
    /**
     * Error message if processing failed
     */
    error?: string;
}
/**
 * Response metadata
 */
export interface H3AggregationMetadata {
    /**
     * Total number of locations requested
     */
    totalRequested: number;
    /**
     * Number of successfully processed locations
     */
    totalSuccessful: number;
    /**
     * Number of failed locations
     */
    totalFailed: number;
    /**
     * Total processing time in milliseconds
     */
    processingTimeMs: number;
    /**
     * H3 resolution used
     */
    resolution: number;
    /**
     * Components included in response
     */
    componentsIncluded: string[];
}
/**
 * Get H3 aggregations endpoint response
 */
export interface GetH3AggregationsResponse {
    /**
     * Success flag (true if at least one location was processed)
     */
    success: boolean;
    /**
     * Array of H3 aggregation results
     */
    results: H3AggregationResult[];
    /**
     * Response metadata
     */
    metadata: H3AggregationMetadata;
    /**
     * Error message (only if all locations failed)
     */
    error?: string;
}