@andreasnicolaou/overpass-client
Version:
A wrapper for the Overpass API to query OpenStreetMap data.
121 lines (85 loc) • 9.52 kB
Markdown
# OverpassClient - Overpass API Wrapper for OpenStreetMap
## Overview
`OverpassClient` is designed to simplify interaction with the Overpass API, used for querying OpenStreetMap (OSM) data. This wrapper provides an easy-to-use interface for retrieving geographic objects like nodes, ways, and relations while handling common issues such as retries, timeouts, and network failures.
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/js/@andreasnicolaou%2Foverpass-client)
[](https://github.com/andreasnicolaou/overpass-client/issues)
[](https://codecov.io/gh/andreasnicolaou/overpass-client)
[](https://github.com/andreasnicolaou/overpass-client/stargazers)
[](https://www.npmjs.com/package/@andreasnicolaou/overpass-client)
## Why?
Interacting with the Overpass API directly can be complex due to common issues like network failures, timeouts, and data size concerns. This wrapper addresses those issues by:
- **Automatic Retries**: The client automatically retries failed requests with exponential backoff and Jitter.
- **Network Resilience**: It reduces downtime caused by intermittent network issues or server limitations.
- **Error Handling**: Gracefully handles Overpass-specific errors, retries, and timeouts, including a custom error class for different error scenarios.
This is ideal for developers who want to interact with OSM data without worrying about low-level request handling and retries.
## Features
- **Axios Integration**: Uses Axios for making HTTP requests, providing flexibility and familiarity.
- **Automatic Retries with Exponential Backoff and Jitter**: Built-in retry logic that progressively delays retries with exponential backoff and jitter to avoid overwhelming the server.
- **Observables**: Handles asynchronous operations efficiently, with easy composition and transformation of the data flow.
- **Node, Way & Relation Support**: Supports querying `node`, `way` and `relation` data, enabling more accurate searches.
- **Caching**: Caches responses to optimize performance for repeated queries, using LRU cache.
- **Flexible Querying**: Easily query elements by ID, bounding box, or radius with customizable tag filters.
## How It Solves Common Problems
1. **Retries and Exponential Backoff**:
- If a request fails, the client automatically retries it with an exponentially increasing delay, including jitter between attempts, ensuring the server isn't overwhelmed.
- This approach significantly improves reliability, especially when dealing with intermittent issues.
2. **Handling Network and Server Failures**:
- The use of Observables, retry logic, and error handling ensures that transient failures (such as network glitches, rate limiting, or API downtime) don't lead to repeated failures, providing a smoother experience for users.
3. **Simplified API**:
- The library abstracts away complex HTTP request handling and error management, allowing developers to focus on higher-level application logic rather than worrying about the specifics of interacting with the Overpass API.
## Installation
```bash
npm install @andreasnicolaou/overpass-client
```
## Usage
### Importing the Library
```typescript
import { OverpassClient } from '@andreasnicolaou/overpass-client';
```
### Initialize the Library
```typescript
this.overpassClient = new OverpassClient();
```
### Query a specific element by ID
```typescript
this.overpassClient.getElement('way', 452).subscribe((response) => {
console.log(response);
});
```
### Query elements within a bounding box
```typescript
const tags = { amenity: ['cafe', 'restaurant'] };
const bbox: [number, number, number, number] = [48.85, 2.29, 48.87, 2.35]; // [minLat, minLon, maxLat, maxLon]
this.overpassClient.getElementsByBoundingBox(tags, bbox).subscribe((response) => {
console.log(response);
});
```
### Query elements within a radius from a center point
```typescript
const lat = 48.85;
const lon = 2.35;
const radius = 500;
this.overpassClient.getElementsByRadius(tags, lat, lon, radius).subscribe((response) => {
console.log(response);
});
```
## API
| Method | Description | Parameters |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clearCache()` | Clear the LRU cache entirely. | None |
| `getElement(type: ElementType, id: number, outputFormat: string = 'out;')` | Fetches a specific element (node, way, or relation) by its ID. | - `type`: The type of element ('node', 'way', 'relation').<br>- `id`: The ID of the element.<br>- `outputFormat`: The Overpass QL output format (default: 'out;'). |
| `getElementsByBoundingBox(tags: Record<string, string[]>, bbox: [number, number, number, number], elements: ElementType[] = ['node', 'way', 'relation'], outputFormat: string = 'out center;')` | Fetches elements with specified tags within a given bounding box. | - `tags`: A dictionary of tag types and their possible values.<br>- `bbox`: A bounding box in the format `[minLat, minLon, maxLat, maxLon]`.<br>- `elements`: The element types to include in the query (default: `'node'`, `'way'`, `'relation'`).<br>- `outputFormat`: The Overpass QL output format (default: 'out center;'). |
| `getElementsByRadius(tags: Record<string, string[]>, lat: number, lon: number, radius: number, elements: ElementType[] = ['node', 'way', 'relation'], outputFormat: string = 'out center;')` | Fetches elements with specified tags within a given radius from a point. | - `tags`: A dictionary of tag types and their possible values.<br>- `lat`: Latitude of the center point.<br>- `lon`: Longitude of the center point.<br>- `radius`: Search radius in meters.<br>- `elements`: The element types to include in the query (default: `'node'`, `'way'`, `'relation'`).<br>- `outputFormat`: The Overpass QL output format (default: 'out center;'). |
## References
- [Overpass API - Public Instances](https://wiki.openstreetmap.org/wiki/Overpass_API#Public_Overpass_API_instances)
- [Overpass Turbo](https://overpass-turbo.eu/)
## Contributing
Contributions are welcome! If you encounter issues or have ideas to enhance the library, feel free to submit an issue or pull request.