Mapping Operations Guide

This skill provides geographic operations using free, no-API-key-required services. All operations work worldwide with reasonable rate limits for typical agent usage.

Geocoding

Convert addresses to coordinates (forward geocoding) or coordinates to addresses (reverse geocoding) using OpenStreetMap's Nominatim service.

Forward geocoding accepts any address format: "1600 Pennsylvania Ave, Washington DC", "Eiffel Tower, Paris", or partial addresses like "Times Square". Results include lat/lon coordinates and a normalized display name. Reverse geocoding accepts lat,lon coordinates and returns the nearest address with components (street, city, country).

Nominatim has a 1 request/second rate limit. For batch operations, add delays between requests. The service works best with specific addresses; vague queries like "good restaurants" won't return useful results.

Static Map Capture

Generate static map images centered on any location. The location can be an address (geocoded automatically) or coordinates.

Important: Static maps show a single location only. They cannot draw routes, paths, markers, or overlays. For route visualization, describe the route textually or use a service that supports route drawing. The map capture is useful for showing "where something is," not "how to get there."

Zoom levels: 1 (world) to 18 (building detail). Common values: 5 (country), 10 (city), 13 (neighborhood), 16 (street). Default is 13.

Map styles:

• street (default) — Standard OpenStreetMap tiles. Roads, buildings, labels.
• topo — OpenTopoMap. Shows elevation contours and terrain features. Use for hiking, outdoor context, or when elevation matters.

Output is a 256x256 PNG tile. For aesthetic transformations (watercolor, vintage, etc.), chain with an image transformation skill.

Distance Calculation

Calculate straight-line (as-the-crow-flies) distance between two points using the Haversine formula. This is geographic distance accounting for Earth's curvature, not driving distance.

Input points as "lat,lon" strings. Output in kilometers or miles. Useful for proximity checks, filtering by distance, or rough travel estimates (multiply by 1.3-1.5 for typical road distance).

Routing and Directions

Get turn-by-turn directions between two locations using OSRM (Open Source Routing Machine). The service calculates actual driving routes on road networks.

Origin and destination can be addresses (geocoded automatically) or coordinates. Output includes total distance, estimated duration, and step-by-step instructions with street names and maneuvers.

The OSRM demo server has rate limits. For heavy usage, consider self-hosting or using a commercial alternative. Route calculations assume car travel; walking/cycling modes are not currently supported.

Common Use Cases

Address verification: Geocode an address, then reverse geocode the result to get a normalized, validated address format.

Location context: Capture a map image to provide visual context for any location-based task.

Proximity filtering: Calculate distances from a central point to filter or sort a list of locations.

Directions generation: Get driving instructions between two points for travel planning or logistics.