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

TypeScript type definitions for Vepler Locations Service

/**
 * Public API types for address endpoints
 */
import { SuccessResponse, ErrorResponse } from '../common';
export { SuccessResponse, ErrorResponse };
/**
 * Query parameters for address record retrieval
 */
export interface AddressRecordQueryParams {
    /**
     * Location ID (UPRN) - can be comma-separated for multiple locations
     */
    locationId: string;
}
/**
 * Query parameters for address search
 */
export interface AddressSearchQueryParams {
    /**
     * Search input string
     */
    input?: string;
    /**
     * Pagination offset
     */
    offset?: number;
    /**
     * Maximum number of results to return
     */
    limit?: number;
}
/**
 * Query parameters for properties on street
 */
export interface StreetPropertiesQueryParams {
    /**
     * Location ID (UPRN) - can be comma-separated for multiple locations
     */
    locationId: string;
}
/**
 * Area search request body
 */
export interface AreaSearchRequest {
    /**
     * Area specification for the search
     */
    area: PostcodeArea | CoordinateArea;
    /**
     * Pagination offset
     */
    offset?: number;
    /**
     * Maximum number of results to return
     */
    limit?: number;
}
/**
 * Postcode area specification
 */
export interface PostcodeArea {
    /**
     * Postcode to search within
     */
    postcode: string;
}
/**
 * Coordinate area specification
 */
export interface CoordinateArea {
    /**
     * Coordinate specification with radius
     */
    coordinate: {
        /**
         * Latitude of the center point (-90 to 90)
         */
        latitude: number;
        /**
         * Longitude of the center point (-180 to 180)
         */
        longitude: number;
        /**
         * Search radius in meters (0-1000)
         */
        radius: number;
    };
}
/**
 * Address response structure
 */
export interface IAddressResponse {
    /**
     * Unique Property Reference Number
     */
    uprn: string;
    /**
     * Formatted full address
     */
    formattedAddress: string;
    /**
     * Organisation name if applicable
     */
    organisationName?: string;
    /**
     * Sub-building name (e.g., Flat A)
     */
    subBuildingName?: string;
    /**
     * Building name
     */
    buildingName?: string;
    /**
     * Building number
     */
    buildingNumber?: string;
    /**
     * Street name
     */
    street?: string;
    /**
     * Dependent locality
     */
    dependentLocality?: string;
    /**
     * Town
     */
    town?: string;
    /**
     * Postcode
     */
    postcode: string;
    /**
     * Postcode outcode (first part before space)
     */
    postcodeOut?: string;
    /**
     * Postcode incode (second part after space)
     */
    postcodeIn?: string;
    /**
     * Classification code
     */
    classificationCode?: string;
    /**
     * Country code (E = England, W = Wales, S = Scotland, N = Northern Ireland)
     */
    countryCode?: string;
    /**
     * Geolocation information
     */
    geo?: {
        /**
         * Latitude coordinate
         */
        latitude: number;
        /**
         * Longitude coordinate
         */
        longitude: number;
    };
}
/**
 * Autocomplete query parameters
 */
export interface AutocompleteQueryParams {
    /**
     * Search query string
     */
    q: string;
    /**
     * Maximum number of results to return
     */
    limit?: number;
    /**
     * Pagination offset
     */
    offset?: number;
    /**
     * Whether to prioritize postcode matches
     */
    postcodePriority?: boolean;
    /**
     * Whether to prioritize street matches
     */
    streetPriority?: boolean;
}
/**
 * Union type for all possible responses
 */
export type AddressResponse<T> = SuccessResponse<T> | ErrorResponse;
/**
 * Specific response types for each endpoint
 */
export type AddressRecordResponse = AddressResponse<IAddressResponse[]>;
export type AddressSearchResponse = AddressResponse<AutocompleteResult[]>;
export type StreetPropertiesResponse = AddressResponse<IAddressResponse[]>;
export type AreaSearchResponse = AddressResponse<IAddressResponse[]>;
/**
 * Highlighted text result
 */
export interface HighlightedResult {
    /**
     * Highlighted sections for different fields
     */
    highlights: {
        /**
         * Street highlight
         */
        street: string | null;
        /**
         * Postcode highlight
         */
        postcode: string | null;
        /**
         * Town highlight
         */
        town?: string | null;
        /**
         * Building name highlight
         */
        buildingName?: string | null;
    };
}
/**
 * Autocomplete result with highlighting
 */
export interface AutocompleteResult extends IAddressResponse, Partial<HighlightedResult> {
    /**
     * Relevance score
     */
    score: number;
    /**
     * Highlighted version of the address
     */
    highlightedAddress?: string;
}