README
¶
OSM Package
This package provides common utilities for working with OpenStreetMap data in the osmmcp project.
Overview
The osm package contains reusable components for interacting with OpenStreetMap services and data. It centralizes various constants, data structures, and utility functions to ensure consistency across the codebase and reduce duplication.
Components
Constants
NominatimBaseURL- Base URL for Nominatim geocoding serviceOverpassBaseURL- Base URL for Overpass API to query OSM dataOSRMBaseURL- Base URL for OSRM routing serviceUserAgent- User agent string to use for API requestsEarthRadius- Earth radius in meters for distance calculations
Functions
NewClient()- Returns a pre-configured HTTP client for OSM API requests with appropriate timeouts and connection poolingHaversineDistance()- Calculates distances between geographic coordinates using the Haversine formulaNewBoundingBox()- Creates a new bounding box for geographic queriesBoundingBox.ExtendWithPoint()- Extends a bounding box to include a pointBoundingBox.Buffer()- Adds a buffer around a bounding boxBoundingBox.String()- Returns a formatted string representation of a bounding box for use in Overpass queries
Usage
import "github.com/NERVsystems/osmmcp/pkg/osm"
// Create an HTTP client
client := osm.NewClient()
// Calculate distance between two points
distance := osm.HaversineDistance(lat1, lon1, lat2, lon2)
// Create and use a bounding box
bbox := osm.NewBoundingBox()
bbox.ExtendWithPoint(lat1, lon1)
bbox.ExtendWithPoint(lat2, lon2)
bbox.Buffer(1000) // Add 1000 meter buffer
Design Principles
The package follows these design principles:
- Single Responsibility: Each component has a clear, focused purpose
- Reusability: Components are designed to be reused across tools
- Abstraction: Implementation details of OSM services are hidden behind clean interfaces
- Consistency: Ensures consistent behavior across different API calls
- Security: Properly configures timeouts and connection limits
Documentation
¶
Overview ¶
Package osm provides utilities for working with OpenStreetMap data.
Package osm provides utilities for working with OpenStreetMap data.
Package osm provides utilities for working with OpenStreetMap data.
Package osm provides utilities for interacting with OpenStreetMap APIs.
Package osm provides utilities for working with OpenStreetMap data.
Index ¶
- Constants
- func DecodePolyline(encoded string) []geo.Location
- func DoRequest(ctx context.Context, req *http.Request) (*http.Response, error)
- func EncodePolyline(points []geo.Location) string
- func GetClient(ctx context.Context) *http.Client
- func GetUserAgent() string
- func HaversineDistance(lat1, lon1, lat2, lon2 float64) float64
- func NewBoundingBox() *geo.BoundingBox
- func NewClient() *http.Client
- func NewRequestWithUserAgent(ctx context.Context, method, url string, body interface{}) (*http.Request, error)
- func SetUserAgent(ua string)
- func UpdateNominatimRateLimits(rps float64, burst int)
- func UpdateOSRMRateLimits(rps float64, burst int)
- func UpdateOverpassRateLimits(rps float64, burst int)
- func ValidateCoords(lat, lon float64) error
- func WaitForService(ctx context.Context, service string) error
- type Client
- type OverpassElement
- type RateLimiter
- type TTLCache
Constants ¶
const ( // Service names for rate limiting ServiceNominatim = "nominatim" ServiceOverpass = "overpass" ServiceOSRM = "osrm" )
const ( // API endpoints NominatimBaseURL = "https://nominatim.openstreetmap.org" OverpassBaseURL = "https://overpass-api.de/api/interpreter" OSRMBaseURL = "https://router.project-osrm.org" // User agent for API requests (required by Nominatim's usage policy) UserAgent = "osm-mcp-server/0.1.0" // Earth radius in meters (approximate) - re-exported from geo package EarthRadius = geo.EarthRadius )
const (
// DefaultUserAgent is the default User-Agent string
DefaultUserAgent = "OSMMCP/0.1.0"
)
Variables ¶
This section is empty.
Functions ¶
func DecodePolyline ¶
DecodePolyline decodes an encoded polyline string to a slice of locations. This implements Google's Polyline Algorithm Format (Polyline5) which is used by OSRM. The algorithm uses 5 decimal places of precision (1e-5) for coordinates. See https://developers.google.com/maps/documentation/utilities/polylinealgorithm
func EncodePolyline ¶
EncodePolyline encodes a slice of locations into a polyline string. This implements Google's Polyline Algorithm Format (Polyline5) which is used by OSRM. The algorithm uses 5 decimal places of precision (1e-5) for coordinates. See https://developers.google.com/maps/documentation/utilities/polylinealgorithm
func HaversineDistance ¶
HaversineDistance calculates the great-circle distance between two points Deprecated: Use geo.HaversineDistance instead
func NewBoundingBox ¶
func NewBoundingBox() *geo.BoundingBox
NewBoundingBox creates a new empty bounding box Deprecated: Use geo.NewBoundingBox instead
func NewClient ¶
NewClient returns an HTTP client configured for OSM API requests Deprecated: Use GetClient(ctx) instead for connection pooling
func NewRequestWithUserAgent ¶
func NewRequestWithUserAgent(ctx context.Context, method, url string, body interface{}) (*http.Request, error)
NewRequestWithUserAgent creates a new HTTP request with proper User-Agent header This simplifies creating requests with the correct header throughout the codebase
func UpdateNominatimRateLimits ¶
UpdateNominatimRateLimits updates the Nominatim rate limiter
func UpdateOSRMRateLimits ¶
UpdateOSRMRateLimits updates the OSRM rate limiter
func UpdateOverpassRateLimits ¶
UpdateOverpassRateLimits updates the Overpass rate limiter
func ValidateCoords ¶
ValidateCoords validates latitude and longitude values Returns an error if the coordinates are invalid
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client represents an OSM API client
type OverpassElement ¶ added in v0.1.1
type OverpassElement struct {
ID int `json:"id"`
Type string `json:"type"`
Lat float64 `json:"lat,omitempty"`
Lon float64 `json:"lon,omitempty"`
Center *struct {
Lat float64 `json:"lat"`
Lon float64 `json:"lon"`
} `json:"center,omitempty"`
Tags map[string]string `json:"tags,omitempty"`
Nodes []int64 `json:"nodes,omitempty"` // For ways, list of node IDs
Members []struct {
Type string `json:"type"`
Ref int64 `json:"ref"`
Role string `json:"role"`
} `json:"members,omitempty"` // For relations
}
OverpassElement represents an element returned from the Overpass API
type RateLimiter ¶
type RateLimiter struct {
// contains filtered or unexported fields
}
RateLimiter manages rate limiting for different OpenStreetMap API services
func GetRateLimiter ¶
func GetRateLimiter() *RateLimiter
GetRateLimiter returns the global rate limiter instance
type TTLCache ¶
type TTLCache[K comparable, V any] struct { // contains filtered or unexported fields }
TTLCache is a generic thread-safe cache with TTL support
func NewTTLCache ¶
func NewTTLCache[K comparable, V any](ttl time.Duration) *TTLCache[K, V]
NewTTLCache creates a new TTL cache with the specified TTL duration
func (*TTLCache[K, V]) Cleanup ¶
func (c *TTLCache[K, V]) Cleanup()
Cleanup removes expired items from the cache
func (*TTLCache[K, V]) Clear ¶
func (c *TTLCache[K, V]) Clear()
Clear removes all items from the cache
func (*TTLCache[K, V]) Delete ¶
func (c *TTLCache[K, V]) Delete(key K)
Delete removes a value from the cache
Source Files
Directories