/**
 * Service for interacting with the Nominatim Geocoding API
 * Documentation: https://nominatim.org/release-docs/latest/api/Search/
 *
 * Nominatim is the geocoding service powering OpenStreetMap.
 * It provides better coverage for small towns and villages compared to GeoNames.
 *
 * Usage Policy: https://operations.osmfoundation.org/policies/nominatim/
 * - Maximum 1 request per second
 * - Requires User-Agent header
 * - No bulk geocoding
 */
import type { MappedGeocodingResponse } from '../types/nominatim.js';
export interface NominatimServiceConfig {
    baseURL?: string;
    timeout?: number;
}
export declare class NominatimService {
    private client;
    private cache;
    private lastRequestTime;
    private readonly MIN_REQUEST_INTERVAL_MS;
    constructor(config?: NominatimServiceConfig);
    /**
     * Handle API errors with helpful status information
     * @private
     */
    private handleError;
    /**
     * Enforce rate limiting (1 request per second as per Nominatim usage policy)
     * @private
     */
    private enforceRateLimit;
    /**
     * Map Nominatim location to GeocodingLocation format for compatibility
     * @private
     */
    private mapLocation;
    /**
     * Map OSM place types to GeoNames-style feature codes
     * @private
     */
    private mapFeatureCode;
    /**
     * Search for locations by name using Nominatim
     *
     * @param query - Location name to search for (e.g., "Paris", "New York, NY", "Tokyo")
     * @param limit - Maximum number of results to return (default: 5, max: 50)
     * @param language - Language for results (default: 'en')
     * @returns Geocoding results with coordinates and metadata
     */
    searchLocation(query: string, limit?: number, language?: string): Promise<MappedGeocodingResponse>;
    /**
     * Resolve the country at a coordinate via Nominatim reverse geocoding
     * (country-level only — `zoom=3`, the privacy-minimal request for this
     * purpose).
     *
     * Open ocean / unresolvable coordinates return HTTP 200 with
     * `{"error": "Unable to geocode"}` — that is a *result* (no country),
     * not a failure, and is cached like any other answer: countries don't
     * move, so a permanent cache applies even to "no country" answers.
     *
     * @param latitude - Latitude
     * @param longitude - Longitude
     * @returns Lowercased ISO 3166-1 alpha-2 country code, or `null` if the
     *   point has no resolvable country (e.g. open ocean).
     */
    reverseCountry(latitude: number, longitude: number): Promise<string | null>;
    /**
     * Get cache statistics
     */
    getCacheStats(): import("../utils/cache.js").CacheStats;
    /**
     * Clear the cache
     */
    clearCache(): void;
}
//# sourceMappingURL=nominatim.d.ts.map