@vepler/area-reference-types/routes/geographic/resolve-geography.d.ts

TypeScript type definitions for Vepler Area Reference API

/**
 * Resolve Geography API Types
 *
 * /geographic/resolve endpoint
 */
import { GeographicEntityType } from '../../common';
import { ResolutionStrategy } from './common';
/**
 * Resolved geography information
 */
export interface ResolvedGeography {
    /**
     * Original input code
     */
    inputCode: string;
    /**
     * Original input type
     */
    inputType: GeographicEntityType;
    /**
     * Resolution strategy used
     */
    strategy: ResolutionStrategy;
    /**
     * Target geography type
     */
    targetType: GeographicEntityType;
    /**
     * Resolved geography codes
     */
    targetCodes: string[];
    /**
     * Detailed target geographies with coverage information
     */
    targetGeographies?: Array<{
        code: string;
        coveragePercentage?: number;
        containmentType?: 'primary' | 'secondary' | 'minimal';
    }>;
    /**
     * Number of resolved entities
     */
    resolvedCount: number;
    /**
     * Whether the resolution covers the full input area
     */
    fullCoverage: boolean;
    /**
     * Additional metadata about the resolution
     */
    metadata?: {
        /**
         * Geographic hierarchy level difference
         */
        levelDifference: number;
        /**
         * Estimated coverage percentage
         */
        coveragePercentage?: number;
        /**
         * Resolution confidence score
         */
        confidence: number;
    };
}
/**
 * Resolve geography query parameters
 */
export interface ResolveGeographyQueryParams {
    /**
     * Input geography code to resolve
     */
    inputCode: string;
    /**
     * Type of the input geography (optional, helps disambiguate when codes are not unique)
     */
    inputType?: GeographicEntityType;
    /**
     * Supported target geography types (comma-separated)
     */
    supportedTiers: string;
    /**
     * Maximum number of child areas to return
     */
    maxChildren?: number;
    /**
     * Whether to allow fallback to parent geography
     */
    allowParentFallback?: boolean;
    /**
     * Spatial strategy for geographic resolution
     * - 'strict': ST_Within (strict containment)
     * - 'centroid': ST_Within(ST_Centroid()) (centroid-based)
     * - 'intersection': ST_Intersects (broader coverage)
     * - 'weighted': Area-weighted intersection threshold
     */
    spatialStrategy?: 'strict' | 'centroid' | 'intersection' | 'weighted';
    /**
     * Intersection threshold for weighted spatial strategy (0.1-0.9)
     * Only used when spatialStrategy is 'weighted'
     */
    intersectionThreshold?: number;
    /**
     * Minimum coverage percentage to include in results (0-100)
     */
    minCoveragePercentage?: number;
    /**
     * Return only the highest coverage geography
     */
    primaryOnly?: boolean;
    /**
     * Calculate and include coverage percentages in response
     */
    includeCoverageInfo?: boolean;
}
/**
 * Alternative resolution option
 */
export interface AlternativeResolution {
    /**
     * Alternative strategy
     */
    strategy: ResolutionStrategy;
    /**
     * Target type for this alternative
     */
    targetType: GeographicEntityType;
    /**
     * Confidence score for this alternative
     */
    confidence: number;
    /**
     * Reason why this alternative exists
     */
    reason: string;
}
/**
 * Resolution response metadata
 */
export interface ResolutionMetadata {
    /**
     * Resolution execution time in milliseconds
     */
    executionTimeMs: number;
    /**
     * Whether result was cached
     */
    cached: boolean;
    /**
     * Alternative resolutions considered
     */
    alternatives?: AlternativeResolution[];
}
/**
 * Resolve geography response
 */
export interface ResolveGeographyResponse {
    /**
     * Success flag
     */
    success: boolean;
    /**
     * Resolution result
     */
    result: ResolvedGeography;
    /**
     * Response metadata
     */
    meta?: ResolutionMetadata;
}