@vepler/locations-types/api/endpoints/enhanced-address-lookup.d.ts

TypeScript type definitions for Vepler Locations Service

/**
 * Public API types for enhanced address lookup endpoint
 */
import { SuccessResponse, ErrorResponse } from '../common';
export { SuccessResponse, ErrorResponse };
/**
 * Request options for enhanced address lookup
 */
export interface AddressLookupOptions {
    /**
     * Minimum confidence threshold for results (0-100)
     * @default 70
     */
    confidenceThreshold?: number;
    /**
     * Fallback confidence threshold (0-100)
     * @default 60
     */
    fallbackThreshold?: number;
    /**
     * Maximum number of results to return (1-10)
     * @default 5
     */
    maxResults?: number;
    /**
     * Enable fallback matching if primary search fails
     * @default true
     */
    enableFallback?: boolean;
    /**
     * Include detailed processing steps in response
     * @default false
     */
    includeProcessingDetails?: boolean;
    /**
     * Request timeout in milliseconds (10000-300000)
     * @default 120000
     */
    timeout?: number;
}
/**
 * Enhanced address lookup request
 */
export interface AddressLookupRequest {
    /**
     * Address string to parse and match against UPRNs
     * Must be between 5-500 characters
     */
    addressString: string;
    /**
     * Optional configuration options
     */
    options?: AddressLookupOptions;
}
/**
 * Address match result
 */
export interface AddressMatch {
    /**
     * Unique Property Reference Number
     */
    uprn: string;
    /**
     * Full formatted address
     */
    address: string;
    /**
     * Confidence score (0-100)
     */
    confidence: number;
    /**
     * Source of the match
     */
    source: 'elasticsearch-exact' | 'elasticsearch-partial' | 'elasticsearch-fuzzy' | 'elasticsearch-direct' | 'postcode-fallback';
    /**
     * Original address string that was searched
     */
    originalAddress: string;
}
/**
 * Processing step information
 */
export interface ProcessingStep {
    /**
     * Step name/identifier
     */
    step: string;
    /**
     * Step execution status
     */
    status: 'success' | 'failed' | 'skipped';
    /**
     * Confidence score for this step
     */
    confidence: number;
    /**
     * Execution time in milliseconds
     */
    executionTimeMs: number;
    /**
     * Additional step details
     */
    details?: string;
}
/**
 * Address lookup response metadata
 */
export interface AddressLookupMetadata {
    /**
     * Number of addresses parsed from input
     */
    addressCount: number;
    /**
     * Total execution time in milliseconds
     */
    executionTimeMs: number;
    /**
     * Address pattern detected
     */
    pattern: 'single' | 'range' | 'multiple' | 'descriptive' | 'complex';
    /**
     * Whether fast-path optimization was used
     */
    fastPath?: boolean;
    /**
     * Detailed processing steps (if requested)
     */
    processingSteps?: ProcessingStep[];
}
/**
 * Address lookup result structure
 */
export interface AddressLookupResult {
    /**
     * Array of matched addresses
     */
    matches: AddressMatch[];
    /**
     * Overall confidence score
     */
    confidence: number;
    /**
     * Response metadata
     */
    metadata: AddressLookupMetadata;
}
/**
 * Enhanced address lookup response - Union of success and error responses
 */
export type AddressLookupResponse = SuccessResponse<AddressLookupResult> | ErrorResponse;
/**
 * Specific named exports for backward compatibility
 */
export type EnhancedAddressLookupRequest = AddressLookupRequest;
export type EnhancedAddressLookupResponse = AddressLookupResponse;