Ground elevation service with S3 caching support
npm install gnd-elevA TypeScript/JavaScript library for fetching ground elevation data using SRTM elevation tiles. Includes built-in caching with configurable TTL and optional S3 storage integration.
- 🌍 High-precision elevation data from SRTM/NASA elevation tiles
- 🚀 Fast & efficient with built-in memory caching
- ☁️ S3 Integration for persistent tile caching
- 📦 Batch processing support for multiple locations
- 🔄 Automatic tile management with configurable TTL
- 📊 Cache statistics and management
- 🎯 Bilinear interpolation for accurate elevation values
- 🛠️ TypeScript first with full type definitions
``bash`
npm install gnd-elevor
yarn add gnd-elevor
bun add gnd-elev
`typescript
import { ElevationService } from "gnd-elev";
// Create an instance
const elevationService = new ElevationService();
// Get elevation for a single location
const locations = [{ lat: 40.7128, lon: -74.006 }];
const elevations = await elevationService.fetchElevationsAsync(locations);
console.log(elevations[0]); // Elevation in meters
`
`typescript
import { ElevationService } from "gnd-elev";
const elevationService = new ElevationService({
s3Storage: {
endpoint: "https://s3.amazonaws.com",
region: "us-east-1",
bucket: "my-elevation-tiles",
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
forcePathStyle: false,
},
ttl: 7200, // Cache tiles for 2 hours
});
const elevations = await elevationService.fetchElevationsAsync([
{ lat: 40.7128, lon: -74.006 },
{ lat: 34.0522, lon: -118.2437 },
]);
`
`typescript
import { ElevationService } from "gnd-elev";
const elevationService = new ElevationService();
// Note: This requires tiles to already be cached
const elevations = elevationService.fetchElevationsSync([{ lat: 40.7128, lon: -74.006 }]);
`
`typescript
// Get cache statistics
const stats = elevationService.getCacheStats();
console.log(stats); // { tiles: 5, downloading: 0, timeouts: 5 }
// Clear cache manually
elevationService.clearCache();
`
#### Constructor
`typescript`
constructor(options?: ElevationOptions)
Options:
- s3Storage (optional): S3 storage configuration for tile cachingendpoint
- : S3 endpoint URLregion
- : AWS regionbucket
- : S3 bucket nameaccessKeyId
- : AWS access key IDsecretAccessKey
- : AWS secret access keyforcePathStyle
- : Force path-style URLs (default: false)ttl
- (optional): Time-to-live for cached tiles in seconds (default: 3600)
#### Methods
##### fetchElevationsAsync(locations: LocationData[]): Promise
Fetch elevations for multiple locations asynchronously.
Parameters:
- locations: Array of { lat: number, lon: number } objects
Returns: Promise resolving to array of elevation values in meters
##### fetchElevationsSync(locations: LocationData[]): number[]
Fetch elevations for multiple locations synchronously (requires tiles to be cached).
Parameters:
- locations: Array of { lat: number, lon: number } objects
Returns: Array of elevation values in meters
##### getCacheStats(): { tiles: number; downloading: number; timeouts: number }
Get current cache statistics.
##### clearCache(): void
Clear all cached tiles and timeouts.
`typescript
type LocationData = {
lat: number;
lon: number;
};
interface S3StorageConfig {
endpoint: string;
region: string;
bucket: string;
accessKeyId: string;
secretAccessKey: string;
forcePathStyle?: boolean;
}
interface ElevationOptions {
s3Storage?: S3StorageConfig;
ttl?: number;
}
`
The service fetches elevation data from:
- Primary: AWS SRTM elevation tiles (elevation-tiles-prod.s3.amazonaws.com`)
- Optional: Custom S3 storage for caching and faster access
1. When you request elevation for a location, the service determines which SRTM tile contains that location
2. If the tile is in memory cache, it's used immediately
3. If not cached, the service checks S3 storage (if configured)
4. If not in S3, it downloads from AWS public SRTM tiles
5. Downloaded tiles are cached in memory with TTL and optionally uploaded to S3
6. Bilinear interpolation is used to calculate precise elevation values
See the examples directory for complete examples, including:
- Express REST API server with elevation endpoints
LGPL-2.1-or-later
Contributions are welcome! Please feel free to submit a Pull Request.