@andreasnicolaou/overpass-client/dist/types/client.d.ts

A wrapper for the Overpass API to query OpenStreetMap data.

import { Observable } from 'rxjs';
import { LRUCache } from 'lru-cache';
export type ElementType = 'node' | 'way' | 'relation';
export type OverpassNode = {
    type: 'node';
    id: number;
    lat: number;
    lon: number;
    tags: Record<string, string>;
};
export type OverpassWay = {
    type: 'way';
    id: number;
    center: {
        lat: number;
        lon: number;
    };
    nodes: number[];
    tags: Record<string, string>;
};
export type OverpassRelation = {
    type: 'relation';
    id: number;
    center: {
        lat: number;
        lon: number;
    };
    members: {
        type: ElementType;
        ref: number;
        role: string;
    }[];
    tags: Record<string, string>;
};
export type OverpassElement = OverpassNode | OverpassWay | OverpassRelation;
export type OverpassResponse = {
    generator: string;
    version: string;
    osm3s: {
        timestamp_osm_base: string;
        copyright: string;
    };
    elements: OverpassElement[];
};
/**
 * A client for querying the Overpass API, supporting caching, retries, and various query types.
 * @class OverpassClient
 * @author Andreas Nicolaou <anicolaou66@gmail.com>
 */
export declare class OverpassClient {
    private readonly axiosInstance;
    private readonly endpoint;
    private readonly format;
    private readonly lruCache;
    private readonly maxRetries;
    private readonly timeout;
    /**
     * Creates a new instance of the Overpass API client.
     * @param endpoint - The Overpass API endpoint to use (default: 'https://overpass-api.de/api/interpreter'). More info at https://wiki.openstreetmap.org/wiki/Overpass_API#Public_Overpass_API_instances
     * @param format - The response format ('json' or 'xml', default: 'json').
     * @param timeout - Query timeout in seconds (default: 60). If set to `0`, the timeout will not be included in the Overpass query.
     * @param maxRetries - Number of automatic retries for failed requests (default: 3).
     * @param lruCache - An optional LRU cache instance for storing query results.
     * @memberof OverpassClient
     */
    constructor(endpoint?: string, format?: 'json' | 'xml', timeout?: number, maxRetries?: number, lruCache?: LRUCache<string, OverpassResponse>);
    /**
     * Clears cache entirely
     * @memberof OverpassClient
     */
    clearCache(): void;
    /**
     * Fetches a specific element (node, way, or relation) by its ID.
     * @param type - The type of element (node, way, or relation).
     * @param id - The ID of the element.
     * @param outputFormat - The Overpass QL output format (default: 'out center;').
     * @returns Observable emitting the query result.
     * @memberof OverpassClient
     */
    getElement(type: ElementType, id: number, outputFormat?: string): Observable<OverpassResponse>;
    /**
     * Fetches elements with specified tags within a given bounding box.
     * @param tags - A dictionary of tag types and their possible values. Example: { amenity: ['cafe', 'restaurant'], tourism: ['museum'] }
     * @param bbox - Bounding box coordinates in the format [minLat, minLon, maxLat, maxLon].
     * @param elements - List of element types to include in the query (node, way, relation). Defaults to all elements.
     * @param outputFormat - The Overpass QL output format (default: 'out center;').
     * @returns Observable emitting the query result.
     * @memberof OverpassClient
     */
    getElementsByBoundingBox(tags: Record<string, string[]>, bbox: [number, number, number, number], elements?: ElementType[], outputFormat?: string): Observable<OverpassResponse>;
    /**
     * Fetches elements with specified tags within a given radius from a point.
     * @param tags - A dictionary of tag types and their possible values. Example: { amenity: ['cafe', 'restaurant'], tourism: ['museum'] }
     * @param lat - Latitude of the center point.
     * @param lon - Longitude of the center point.
     * @param radius - Search radius in meters.
     * @param elements - List of element types to include in the query (node, way, relation). Defaults to all elements.
     * @param outputFormat - The Overpass QL output format (default: 'out center;').
     * @returns Observable emitting the query result.
     * @memberof OverpassClient
     */
    getElementsByRadius(tags: Record<string, string[]>, lat: number, lon: number, radius: number, elements?: ElementType[], outputFormat?: string): Observable<OverpassResponse>;
    /**
     * Executes an Overpass QL query with automatic retries using RxJS Observables.
     * @param query - The Overpass QL query string.
     * @param cachedKey - The cache key for storing the query result.
     * @returns Observable emitting the query result.
     * @memberof OverpassClient
     */
    private query;
    /**
     * Calculates the retry delay using exponential backoff with jitter.
     * If a `retryAfterMs` value is provided (for 429 errors), it is used directly.
     * @param attempt
     * @param [retryAfterMs]
     * @returns after
     */
    private retryAfter;
}