@vepler/area-reference-types/routes/metrics/get-metric-values.d.ts

TypeScript type definitions for Vepler Area Reference API

/**
 * Get Metric Values API Types
 *
 * /api/metrics/values endpoint
 */
import { GeographicEntityType } from '../../common';
import { MetricDataType } from './common';
/**
 * Metric value with geographic context
 */
export interface MetricValue {
    /**
     * Geographic entity code
     */
    entityCode: string;
    /**
     * Geographic entity type
     */
    entityType: GeographicEntityType;
    /**
     * Metric identifier
     */
    metricId: string;
    /**
     * Metric value
     */
    value: number | string | boolean;
    /**
     * Data period timestamp
     */
    dataPeriod: string;
    /**
     * Area information
     */
    areaInfo?: {
        /**
         * Human-readable area name
         */
        name: string;
        /**
         * Area type description
         */
        typeDescription: string;
    };
    /**
     * Metric metadata
     */
    metricInfo?: {
        /**
         * Metric display name
         */
        name: string;
        /**
         * Metric description
         */
        description: string;
        /**
         * Metric unit of measurement
         */
        unit: string;
        /**
         * Data type
         */
        dataType: MetricDataType;
    };
}
/**
 * Get metric values query parameters
 */
export interface GetMetricValuesQueryParams {
    /**
     * Metric identifiers to retrieve (comma-separated)
     */
    metricIds?: string;
    /**
     * Geographic entity IDs (comma-separated)
     */
    geographicEntityIds?: string;
    /**
     * Geographic entity types to filter by (comma-separated)
     */
    geographicEntityTypes?: string;
    /**
     * Start year for filtering
     */
    startYear?: number;
    /**
     * End year for filtering
     */
    endYear?: number;
    /**
     * Start month for filtering (1-12)
     */
    startMonth?: number;
    /**
     * End month for filtering (1-12)
     */
    endMonth?: number;
    /**
     * Source services to filter by (comma-separated)
     */
    sourceServices?: string;
    /**
     * Maximum number of results
     */
    limit?: number;
    /**
     * Result offset for pagination
     */
    offset?: number;
    /**
     * Sort field
     */
    sortBy?: 'value' | 'year' | 'month';
    /**
     * Sort order
     */
    sortOrder?: 'ASC' | 'DESC';
    /**
     * Include metric metadata in response
     */
    includeMetric?: boolean;
    /**
     * Include geographic entity information in response
     */
    includeGeographicEntity?: boolean;
    /**
     * Comma-separated list of attributes to include
     */
    attributes?: string;
}
/**
 * Applied filters metadata
 */
export interface AppliedFilters {
    /**
     * Metric IDs that were queried
     */
    metricIds: string[];
    /**
     * Entity codes that were filtered
     */
    entityCodes?: string[];
    /**
     * Entity types that were filtered
     */
    entityTypes?: GeographicEntityType[];
    /**
     * Date period filters
     */
    datePeriod?: {
        start?: string;
        end?: string;
        specific?: string;
    };
}
/**
 * Pagination metadata
 */
export interface PaginationMetadata {
    /**
     * Total number of results
     */
    total: number;
    /**
     * Current limit
     */
    limit: number;
    /**
     * Current offset
     */
    offset: number;
    /**
     * Whether there are more results
     */
    hasMore: boolean;
}
/**
 * Performance metadata
 */
export interface PerformanceMetadata {
    /**
     * Query execution time in milliseconds
     */
    executionTimeMs: number;
    /**
     * Whether result was served from cache
     */
    cacheHit: boolean;
}
/**
 * Get metric values response
 */
export interface GetMetricValuesResponse {
    /**
     * Success flag
     */
    success: boolean;
    /**
     * Total count of metric values
     */
    count: number;
    /**
     * Array of metric values
     */
    result: MetricValue[];
    /**
     * Response metadata
     */
    meta?: {
        /**
         * Applied filters
         */
        filters: AppliedFilters;
        /**
         * Pagination information
         */
        pagination: PaginationMetadata;
        /**
         * Query performance
         */
        performance?: PerformanceMetadata;
    };
}