feat(api): add Distance API for distance and duration calculations

[sylvesterdamgaard]

Summary

Adds a comprehensive Distance API to the Geocodio OpenAPI specification, enabling distance and duration calculations between coordinates with multiple modes of operation.

Changes

New Endpoints

• GET /distance - Quick 1→1 or 1→N distance calculations via query parameters
• POST /distance - M×N matrix calculations and nearest-neighbor queries
• POST /distance/jobs - Async job creation for large matrix calculations (>10,000 elements)
• GET /distance/jobs - List distance calculation jobs
• GET /distance/jobs/{job_id} - Get job status and results

Enhanced Existing Endpoints

• GET /geocode - Added distance_* parameters for inline distance calculations
• POST /geocode - Extended batch request schemas to support per-row distance queries and matrix operations

New Features

• Calculation modes: haversine (straight-line) and driving (route-based with duration)
• Unit selection: miles or km
• Filtering options: max_results, max_distance, max_duration
• Sorting: Order by distance or duration
• ID support: Optional user-defined IDs for origins/destinations
• Async processing: Webhook callbacks for large jobs

New Schema Components

• GeocodingResultWithDistance - Geocoding result with inline distance data
• DistanceQuery, DistanceTarget - Distance query structures
• DistanceGetResponse, DistanceMatrixResponse, DistanceNearestResponse - Response schemas
• DistanceJobResponse, DistanceJobCompletedResponse - Async job schemas
• Multiple request/response schemas for batch operations

Test Plan

• Validate OpenAPI spec with swagger-cli validate geocodio-api.yml or similar tool
• Verify spec renders correctly in Swagger UI / ReDoc
• Review example responses for accuracy and completeness
• Confirm all $ref paths resolve correctly
• Test spec compatibility with OpenAPI code generators