@vepler/locations-types/api/endpoints/canonical-location.d.ts

TypeScript type definitions for Vepler Locations Service

/**
 * Public API types for canonical location autocomplete
 */
/**
 * Import base response types from common module for consistency
 */
import { SuccessResponse, ErrorResponse } from '../common';
/**
 * Canonical location autocomplete query parameters
 */
export interface CanonicalAutocompleteQueryParams {
    /**
     * Search query string
     */
    q: string;
    /**
     * Maximum number of results to return (1-100)
     */
    limit?: number;
    /**
     * Geographic filters
     */
    country?: string;
    region?: string;
    county?: string;
    /**
     * Location type filters
     */
    locationType?: string[];
    /**
     * Minimum importance score (0.0-1.0)
     */
    minImportance?: number;
    /**
     * Geographic proximity search
     */
    latitude?: number;
    longitude?: number;
    radiusKm?: number;
    /**
     * Include enriched search variants in results
     */
    includeEnrichment?: boolean;
}
/**
 * Canonical location autocomplete result
 */
export interface CanonicalAutocompleteResult {
    /**
     * Canonical record ID
     */
    recordId: number;
    /**
     * Display name for the location
     */
    displayName: string;
    /**
     * Canonical normalized name
     */
    canonicalName: string;
    /**
     * Location types
     */
    types: string[];
    /**
     * Primary location type (from enrichment)
     */
    primaryType?: string;
    /**
     * Geographic coordinates
     */
    geo: {
        lat: number;
        lon: number;
    };
    /**
     * Administrative hierarchy (only includes primary and canonical entities)
     * Hierarchy entities are filtered out but available in _relationshipMeta
     */
    administrativeHierarchy: {
        country?: string;
        region?: string;
        county?: string;
        district?: string;
        locality?: string;
        /**
         * Metadata about relationship types and sources for administrative entities
         * This provides context about how each administrative entity relates to the location
         * Includes ALL entities (primary, canonical, and hierarchy) for full context
         */
        _relationshipMeta?: {
            country?: {
                relationshipType: 'primary' | 'canonical' | 'hierarchy' | 'unclassified';
                source: string;
                entityId: string;
            };
            region?: {
                relationshipType: 'primary' | 'canonical' | 'hierarchy' | 'unclassified';
                source: string;
                entityId: string;
            };
            county?: {
                relationshipType: 'primary' | 'canonical' | 'hierarchy' | 'unclassified';
                source: string;
                entityId: string;
            };
            district?: {
                relationshipType: 'primary' | 'canonical' | 'hierarchy' | 'unclassified';
                source: string;
                entityId: string;
            };
            locality?: {
                relationshipType: 'primary' | 'canonical' | 'hierarchy' | 'unclassified';
                source: string;
                entityId: string;
            };
        };
    };
    /**
     * Search relevance score (raw Elasticsearch score)
     */
    score: number;
    /**
     * Standardised confidence score (0.0-1.0)
     */
    confidence: number;
    /**
     * Search boost score
     */
    searchBoost: number;
    /**
     * Importance score
     */
    importanceScore: number;
    /**
     * Display information
     */
    display: {
        label: string;
        badge?: string;
        description?: string;
    };
    /**
     * Enriched search description (if available)
     */
    enrichedDescription?: string;
    /**
     * Search tags (if enriched)
     */
    searchTags?: string[];
    /**
     * Number of source records in this canonical
     */
    memberCount: number;
    /**
     * Search highlighting
     */
    highlights?: {
        canonicalName?: string;
        searchVariants?: string[];
        searchTags?: string[];
        description?: string;
    };
    /**
     * Enrichment metadata (if available)
     */
    enrichmentMeta?: {
        confidence: number;
        llmModel: string;
        version: number;
    };
}
/**
 * Canonical success response structure - extends base response
 */
export interface CanonicalSuccessResponse<T> extends SuccessResponse<T> {
    /**
     * Enhanced metadata for canonical locations
     */
    meta?: SuccessResponse<T>['meta'] & {
        /**
         * Total count of matching records
         */
        total: number;
        /**
         * Results limit
         */
        limit: number;
        /**
         * Query used for search
         */
        query: string;
        /**
         * Applied filters
         */
        filters?: {
            country?: string;
            region?: string;
            county?: string;
            locationType?: string[];
            minImportance?: number;
            proximitySearch?: {
                latitude: number;
                longitude: number;
                radiusKm: number;
            };
        };
    };
}
/**
 * Canonical error response structure - uses base error response
 */
export interface CanonicalErrorResponse extends ErrorResponse {
}
/**
 * Union type for canonical location responses
 */
export type CanonicalLocationResponse<T> = CanonicalSuccessResponse<T> | CanonicalErrorResponse;