feat(distance): Add full Distance API support #20
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add DistanceMode enum (Straightline, Driving, Haversine) - Add DistanceUnits enum (Miles, Km) - Add DistanceOrderBy enum (Distance, Duration) - Add DistanceSortOrder enum (Asc, Desc) - Add Coordinate readonly class for type-safe coordinate handling with lat/lng validation and optional ID support
Add distance calculation methods: - distance() - single origin to multiple destinations (GET) - distanceMatrix() - multiple origins × destinations (POST) Add async distance matrix job methods: - createDistanceMatrixJob() - create background job - distanceMatrixJobStatus() - check job status - distanceMatrixJobs() - list all jobs - getDistanceMatrixJobResults() - get parsed results - downloadDistanceMatrixJob() - download to file - deleteDistanceMatrixJob() - delete job Add distance support to geocoding: - geocode() with destinations parameter - reverse() with destinations parameter Features: - Type-safe enums for mode, units, orderBy, sortOrder - Coordinate DTO with object format for POST requests - Haversine→straightline mapping for backward compat - Filtering: maxResults, maxDistance, maxDuration, etc. - Custom IDs for tracking origins/destinations
Add comprehensive test coverage for: - GET /distance endpoint with various coordinate formats - POST /distance matrix endpoint - Nearest mode with filtering options - Haversine mode backward compatibility - Custom ID support for coordinates
Document all distance features: - Coordinate format with custom IDs - Distance mode and units enums - Add distance to geocode/reverse requests - Single origin to multiple destinations - Distance matrix (multiple origins × destinations) - Nearest mode filtering options - Async distance matrix jobs Reorganize TOC: move distance after uploading lists
Prevents misidentifying invalid coordinates with range validation: - Latitude must be between -90 and 90 - Longitude must be between -180 and 180 This catches obvious non-coordinates like '123, 456' while accepting valid integer coordinates like '38,-77'.
API uses 'kilometers' not 'km', update enum to match.
This reverts commit 8b5a113.
MiniCodeMonkey
approved these changes
Dec 16, 2025
- distanceMatrix() now uses POST /distance-matrix - Async job endpoints moved from /distance-matrix to /distance-jobs
- Remove invalid @var annotations on constants - Change Response to ResponseInterface for proper PSR-7 compliance - Add never return type to handleException() method
MiniCodeMonkey
approved these changes
Dec 17, 2025
- Remove Haversine from enum documentation - Use named parameters in geocode example - Update billing note to reference pricing page
The API supports both 'haversine' and 'straightline' mode values directly, so the SDK-side conversion is redundant.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Add comprehensive Distance API support to the Geocodio PHP SDK, enabling distance calculations between coordinates with type-safe enums and a new Coordinate DTO class.
Changes
New Enums
DistanceMode- Straightline, Driving, Haversine (backward compat alias)DistanceUnits- Miles, KmDistanceOrderBy- Distance, DurationDistanceSortOrder- Asc, DescNew Coordinate DTO
Coordinatereadonly class with lat/lng validationlat,lng,id) and object format for APINew Distance Methods
distance()- Calculate from single origin to multiple destinations (GET)distanceMatrix()- Calculate full matrix: multiple origins × destinations (POST)Async Distance Matrix Jobs
createDistanceMatrixJob()- Create background processing jobdistanceMatrixJobStatus()- Check job statusdistanceMatrixJobs()- List all jobs (paginated)getDistanceMatrixJobResults()- Get parsed JSON resultsdownloadDistanceMatrixJob()- Download results to filedeleteDistanceMatrixJob()- Delete a jobEnhanced Geocoding
geocode()now acceptsdestinationsparameter for distance calculationsreverse()now acceptsdestinationsparameter for distance calculationsDocumentation
Test Plan