geocodio-gem 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7edbfd26554e922c6d274ef187e68595dc9f824089afc29817c70664f7289c63
-  data.tar.gz: fdf4febbc8917dc38dd128343680a146fb69164670cbd7c98b669c26fbb7ab05
+  metadata.gz: 0dcf45fbaa749a3272901c9448961eadc96adcd24f8d1122ab9ae691e76ad30e
+  data.tar.gz: 3f26bbc4c74fe7b9062d952615d7de520d4ef3043d41d0bc3cfb02fa5def5f97
 SHA512:
-  metadata.gz: 358ee3b3599c87ab971d04d202c55596d4c3179c729f8c8742fdec7c96c72bbdaa748553cac3716d6546dadf09a9b28a8959bc253e3b33f41612466ad39c85b4
-  data.tar.gz: 36833379cf833c4ff78b5bc97c2267e8720cca21242c00bf31c8733738120a146df3bd10648a3d7da6bac64e386cd09afa4ff1c638b8f996ef0f2b63c21b98f5
+  metadata.gz: fc0809146e16875b323b13da38765f1a2267238f6956dc9f0a04deca4a01f6a50ea427419d6ef6a123009303ab58e3d59f37329e4e80baea943dde16a5ed2582
+  data.tar.gz: d04e79756c2c7fb4682f26d928f40239634f0d20782df767356021d69b9afcf0622ad7fb833774c0f88a59b85f93823bef13b4d35dca6dde835236960c21ccec

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.5.0] - 2026-01-06
+- Added Distance API support:
+  - `distance()` - Calculate distances from single origin to multiple destinations
+  - `distanceMatrix()` - Calculate full distance matrix (multiple origins x destinations)
+  - `createDistanceMatrixJob()` - Create async distance matrix jobs
+  - `distanceMatrixJobStatus()` - Check job status
+  - `distanceMatrixJobs()` - List all distance jobs
+  - `getDistanceMatrixJobResults()` - Get completed job results
+  - `downloadDistanceMatrixJob()` - Download results to file
+  - `deleteDistanceMatrixJob()` - Delete a job
+- Enhanced `geocode()` and `reverse()` with optional distance parameters
+- Support for multiple coordinate formats (string, array, hash) with optional IDs
+- Support for driving mode with duration estimates
+- Support for distance filtering options (max_results, max_distance, etc.)
+- Updated API endpoint from v1.8 to v1.9
+
 ## [0.3.0] - 2025-5-20
 - Updated API endpoint from v1.7 to v1.8
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    geocodio-gem (0.3.0)
+    geocodio-gem (0.5.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -213,6 +213,233 @@ To use `deleteList()`, pass in the ID of the list you would like to delete.
     response # => {"success"=>true}
 ```
 
+## Distance Calculations
+
+The Distance API allows you to calculate distances from a single origin to multiple destinations, or compute full distance matrices.
+
+### Coordinate Formats with Custom IDs
+
+You can add custom identifiers to coordinates using various formats. The ID will be returned in the response, making it easy to match results back to your data:
+
+```ruby
+# String format with ID
+"37.7749,-122.4194,warehouse_1"
+
+# Array format with ID
+[37.7749, -122.4194, "warehouse_1"]
+
+# Hash format with ID
+{ lat: 37.7749, lng: -122.4194, id: "warehouse_1" }
+```
+
+### Distance Mode and Units
+
+The SDK supports different distance calculation modes and units:
+
+```ruby
+# Available modes
+:straightline  # Default - great-circle (as the crow flies)
+:driving       # Road network routing with duration
+:haversine     # Alias for straightline (backward compatibility)
+
+# Available units
+:miles         # Default
+:kilometers
+```
+
+> **Note:** The default mode is `:straightline` (great-circle distance). Use `:driving` if you need road network routing with duration estimates.
+
+### Single Origin to Multiple Destinations
+
+Calculate distances from one origin to multiple destinations:
+
+```ruby
+# Basic usage with string coordinates
+response = geocodio.distance(
+  "38.8977,-77.0365,white_house",
+  ["38.9072,-77.0369,capitol", "38.8895,-77.0353,monument"]
+)
+
+response["origin"]["id"]  # => "white_house"
+response["destinations"][0]["distance_miles"]  # => 0.7
+response["destinations"][0]["id"]  # => "capitol"
+
+# With driving mode (includes duration)
+response = geocodio.distance(
+  "38.8977,-77.0365",
+  ["38.9072,-77.0369"],
+  mode: :driving
+)
+
+response["destinations"][0]["duration_seconds"]  # => 180
+
+# With filtering and sorting options
+response = geocodio.distance(
+  "38.8977,-77.0365,warehouse",
+  [
+    "38.9072,-77.0369,store_1",
+    "39.2904,-76.6122,store_2",
+    "39.9526,-75.1652,store_3"
+  ],
+  mode: :driving,
+  units: :kilometers,
+  max_results: 2,
+  max_distance: 100.0,
+  order_by: :distance,
+  sort: :asc
+)
+
+# Using array format for coordinates
+response = geocodio.distance(
+  [38.8977, -77.0365, "headquarters"],
+  [[38.9072, -77.0369, "branch_1"]]
+)
+
+# Using hash format for coordinates
+response = geocodio.distance(
+  { lat: 38.8977, lng: -77.0365, id: "hq" },
+  [{ lat: 38.9072, lng: -77.0369, id: "branch" }]
+)
+```
+
+### Distance Matrix (Multiple Origins to Multiple Destinations)
+
+Calculate full distance matrix from multiple origins to multiple destinations:
+
+```ruby
+origins = [
+  "38.8977,-77.0365,warehouse_dc",
+  "39.2904,-76.6122,warehouse_baltimore"
+]
+destinations = [
+  "38.9072,-77.0369,customer_1",
+  "39.9526,-75.1652,customer_2"
+]
+
+response = geocodio.distanceMatrix(origins, destinations)
+
+response["results"][0]["origin"]["id"]  # => "warehouse_dc"
+response["results"][0]["destinations"][0]["distance_miles"]  # => 0.7
+
+# With driving mode
+response = geocodio.distanceMatrix(
+  origins,
+  destinations,
+  mode: :driving,
+  units: :kilometers
+)
+
+# With filtering options
+response = geocodio.distanceMatrix(
+  origins,
+  destinations,
+  max_results: 2,
+  max_distance: 50.0,
+  min_distance: 1.0,
+  order_by: :distance,
+  sort: :asc
+)
+```
+
+### Add Distance to Geocoding Requests
+
+You can add distance calculations to existing geocode or reverse geocode requests:
+
+```ruby
+# Geocode an address and calculate distances to store locations
+response = geocodio.geocode(
+  ["1600 Pennsylvania Ave NW, Washington DC"],
+  [],     # fields
+  nil,    # limit
+  nil,    # format
+  destinations: [
+    "38.9072,-77.0369,store_dc",
+    "39.2904,-76.6122,store_baltimore"
+  ],
+  distance_mode: :driving,
+  distance_units: :miles
+)
+
+response["results"][0]["destinations"][0]["distance_miles"]  # => distance to first destination
+response["results"][0]["destinations"][0]["id"]  # => "store_dc"
+
+# Reverse geocode with distances
+response = geocodio.reverse(
+  ["38.8977,-77.0365"],
+  [],
+  nil,
+  nil,
+  destinations: ["38.9072,-77.0369,capitol"],
+  distance_mode: :straightline
+)
+
+response["results"][0]["destinations"]  # => array of destinations with distances
+```
+
+### Async Distance Matrix Jobs
+
+For large distance matrix calculations, use async jobs that process in the background:
+
+```ruby
+# Create a new distance matrix job
+job = geocodio.createDistanceMatrixJob(
+  "My Distance Calculation",
+  ["38.8977,-77.0365,origin_1", "38.9072,-77.0369,origin_2"],
+  ["38.8895,-77.0353,dest_1", "39.2904,-76.6122,dest_2"],
+  mode: :driving,
+  units: :miles,
+  callback_url: "https://example.com/webhook"  # Optional
+)
+
+job["id"]  # => Job identifier
+
+# Or use list IDs from previously uploaded lists
+job = geocodio.createDistanceMatrixJob(
+  "Distance from Lists",
+  12345,    # List ID for origins
+  67890,    # List ID for destinations
+  mode: :straightline
+)
+
+# Check job status
+status = geocodio.distanceMatrixJobStatus(job["id"])
+
+status["data"]["status"]  # => "COMPLETED", "PROCESSING", or "FAILED"
+status["data"]["progress"]  # => 0-100
+
+# List all jobs (paginated)
+jobs = geocodio.distanceMatrixJobs
+jobs = geocodio.distanceMatrixJobs(2)  # Page 2
+
+# Get job results as parsed hash
+results = geocodio.getDistanceMatrixJobResults(job["id"])
+
+results["results"][0]["origin"]["id"]  # => "origin_1"
+results["results"][0]["destinations"]  # => array of destinations with distances
+
+# Download results to file
+geocodio.downloadDistanceMatrixJob(job["id"], "/path/to/results.json")
+
+# Delete a job
+geocodio.deleteDistanceMatrixJob(job["id"])
+```
+
+### Distance Filtering Options
+
+All distance methods support the following filtering options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `mode` | Symbol | `:straightline` (default), `:driving`, or `:haversine` |
+| `units` | Symbol | `:miles` (default), `:kilometers`, or `:km` |
+| `max_results` | Integer | Limit number of results |
+| `max_distance` | Float | Filter by maximum distance |
+| `min_distance` | Float | Filter by minimum distance |
+| `max_duration` | Integer | Filter by max duration in seconds (driving mode only) |
+| `min_duration` | Integer | Filter by min duration in seconds (driving mode only) |
+| `order_by` | Symbol | `:distance` (default) or `:duration` |
+| `sort` | Symbol | `:asc` (default) or `:desc` |
+
 ## Testing
 
 To run tests, be sure to create a `.env` file that export your Geocodio API Key within a variable of API_KEY. 

data/lib/geocodio/gem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Geocodio
-    VERSION = "0.3.0"
+    VERSION = "0.5.0"
 end

data/lib/geocodio/gem.rb

@@ -2,6 +2,7 @@ require_relative "gem/version"
 require "faraday"
 require "faraday/follow_redirects"
 require "csv"
+require "uri"
 
 module Geocodio
 
@@ -14,7 +15,7 @@ module Geocodio
       @api_key = api_key
 
       @conn = Faraday.new(
-        url: 'https://api.geocod.io/v1.8/',
+        url: 'https://api.geocod.io/v1.9/',
         headers: {'Content-Type' => 'application/json' }
       ) do |f|
         f.response :follow_redirects
@@ -22,11 +23,34 @@ module Geocodio
       end
     end
 
-    def geocode(query=[], fields=[], limit=nil, format=nil)
+    # Forward geocode addresses to coordinates
+    # @param query [Array] Array of address strings
+    # @param fields [Array] Optional fields to append (e.g., ["timezone", "cd"])
+    # @param limit [Integer] Maximum number of results
+    # @param format [String] Response format ("simple" for simplified response)
+    # @param destinations [Array] Optional array of destination coordinates for distance calculation
+    # @param distance_mode [Symbol] Distance mode (:straightline, :driving, :haversine)
+    # @param distance_units [Symbol] Distance units (:miles, :kilometers)
+    # @param distance_options [Hash] Additional distance options (max_results, max_distance, etc.)
+    def geocode(query=[], fields=[], limit=nil, format=nil,
+                destinations: nil, distance_mode: nil, distance_units: nil, distance_options: nil)
       if query.size < 1
         raise ArgumentError, 'Please provide at least one address to geocode.'
-      elsif query.size == 1 
-        response = JSON.parse(@conn.get('geocode', { q: query.join(""), fields: fields.join(","), limit: limit, format: format, api_key: @api_key }).body)
+      elsif query.size == 1
+        # Build query string manually to handle array parameters correctly
+        query_parts = [
+          "api_key=#{@api_key}",
+          "q=#{URI.encode_www_form_component(query.join(""))}"
+        ]
+        query_parts << "fields=#{URI.encode_www_form_component(fields.join(","))}" if fields && !fields.empty?
+        query_parts << "limit=#{limit}" if limit
+        query_parts << "format=#{format}" if format
+
+        # Add distance parameters if destinations provided
+        distance_parts = build_geocode_distance_query_parts(destinations, distance_mode, distance_units, distance_options)
+        query_parts.concat(distance_parts)
+
+        response = JSON.parse(@conn.get("geocode?#{query_parts.join('&')}").body)
         return response
       elsif query.size > 1
         response = @conn.post('geocode') do |req|
@@ -39,11 +63,34 @@ module Geocodio
       end
     end
 
-    def reverse(query=[], fields=[], limit=nil, format=nil)
+    # Reverse geocode coordinates to addresses
+    # @param query [Array] Array of coordinate strings ("lat,lng")
+    # @param fields [Array] Optional fields to append (e.g., ["timezone", "cd"])
+    # @param limit [Integer] Maximum number of results
+    # @param format [String] Response format ("simple" for simplified response)
+    # @param destinations [Array] Optional array of destination coordinates for distance calculation
+    # @param distance_mode [Symbol] Distance mode (:straightline, :driving, :haversine)
+    # @param distance_units [Symbol] Distance units (:miles, :kilometers)
+    # @param distance_options [Hash] Additional distance options (max_results, max_distance, etc.)
+    def reverse(query=[], fields=[], limit=nil, format=nil,
+                destinations: nil, distance_mode: nil, distance_units: nil, distance_options: nil)
       if query.size < 1
         raise ArgumentError, 'Please provide at least one set of coordinates to geocode.'
       elsif query.size == 1
-        response = JSON.parse(@conn.get('reverse', { q: query.join(""), fields: fields.join(","), limit: limit, format: format, api_key: @api_key}).body)
+        # Build query string manually to handle array parameters correctly
+        query_parts = [
+          "api_key=#{@api_key}",
+          "q=#{URI.encode_www_form_component(query.join(""))}"
+        ]
+        query_parts << "fields=#{URI.encode_www_form_component(fields.join(","))}" if fields && !fields.empty?
+        query_parts << "limit=#{limit}" if limit
+        query_parts << "format=#{format}" if format
+
+        # Add distance parameters if destinations provided
+        distance_parts = build_geocode_distance_query_parts(destinations, distance_mode, distance_units, distance_options)
+        query_parts.concat(distance_parts)
+
+        response = JSON.parse(@conn.get("reverse?#{query_parts.join('&')}").body)
         return response
       elsif query.size > 1
         response = @conn.post('reverse') do |req|
@@ -96,6 +143,294 @@ module Geocodio
       response = JSON.parse(@conn.delete("lists/#{id}", { api_key: @api_key}).body)
       return response
     end
+
+    # Distance API Methods
+
+    # Calculate distances from a single origin to multiple destinations
+    # @param origin [String, Array, Hash] Origin coordinate ("lat,lng" or "lat,lng,id" or [lat, lng] or [lat, lng, id] or {lat:, lng:, id:})
+    # @param destinations [Array] Array of destination coordinates in any supported format
+    # @param options [Hash] Optional parameters:
+    #   - mode: :straightline (default), :driving, or :haversine (alias for straightline)
+    #   - units: :miles (default) or :kilometers
+    #   - max_results: Integer, limit number of results
+    #   - max_distance: Float, filter by max distance
+    #   - max_duration: Integer, filter by max duration (seconds, driving only)
+    #   - min_distance: Float, filter by min distance
+    #   - min_duration: Integer, filter by min duration (seconds, driving only)
+    #   - order_by: :distance (default) or :duration
+    #   - sort: :asc (default) or :desc
+    def distance(origin, destinations, options = {})
+      raise ArgumentError, 'Please provide an origin coordinate.' if origin.nil?
+      raise ArgumentError, 'Please provide at least one destination.' if destinations.nil? || destinations.empty?
+
+      # Build query string manually to handle array parameters correctly
+      query_parts = [
+        "api_key=#{@api_key}",
+        "origin=#{URI.encode_www_form_component(format_coordinate_string(origin))}"
+      ]
+
+      # Add destinations as properly formatted array parameters
+      destinations.each do |dest|
+        query_parts << "destinations[]=#{URI.encode_www_form_component(format_coordinate_string(dest))}"
+      end
+
+      # Add distance options
+      build_distance_params(options).each do |key, value|
+        query_parts << "#{key}=#{URI.encode_www_form_component(value.to_s)}"
+      end
+
+      response = JSON.parse(@conn.get("distance?#{query_parts.join('&')}").body)
+      return response
+    end
+
+    # Calculate distance matrix from multiple origins to multiple destinations
+    # @param origins [Array] Array of origin coordinates
+    # @param destinations [Array] Array of destination coordinates
+    # @param options [Hash] Same options as distance() method
+    def distanceMatrix(origins, destinations, options = {})
+      raise ArgumentError, 'Please provide at least one origin.' if origins.nil? || origins.empty?
+      raise ArgumentError, 'Please provide at least one destination.' if destinations.nil? || destinations.empty?
+
+      body = {
+        origins: origins.map { |coord| format_coordinate_object(coord) },
+        destinations: destinations.map { |coord| format_coordinate_object(coord) }
+      }
+
+      # Add distance options to body
+      body.merge!(build_distance_body_params(options))
+
+      response = @conn.post('distance-matrix') do |req|
+        req.params = { api_key: @api_key }
+        req.headers['Content-Type'] = 'application/json'
+        req.body = body.to_json
+      end
+
+      parsed = JSON.parse(response.body)
+      return parsed
+    end
+
+    # Create an async distance matrix job
+    # @param name [String] Job name
+    # @param origins [Array, Integer] Array of coordinates or list ID
+    # @param destinations [Array, Integer] Array of coordinates or list ID
+    # @param options [Hash] Same options as distanceMatrix() plus:
+    #   - callback_url: URL for webhook notification
+    def createDistanceMatrixJob(name, origins, destinations, options = {})
+      raise ArgumentError, 'Please provide a job name.' if name.nil? || name.empty?
+      raise ArgumentError, 'Please provide origins.' if origins.nil?
+      raise ArgumentError, 'Please provide destinations.' if destinations.nil?
+
+      body = { name: name }
+
+      # Origins can be array of coordinates or list ID (integer)
+      if origins.is_a?(Integer)
+        body[:origins] = origins
+      else
+        body[:origins] = origins.map { |coord| format_coordinate_object(coord) }
+      end
+
+      # Destinations can be array of coordinates or list ID (integer)
+      if destinations.is_a?(Integer)
+        body[:destinations] = destinations
+      else
+        body[:destinations] = destinations.map { |coord| format_coordinate_object(coord) }
+      end
+
+      # Add distance options
+      body.merge!(build_distance_body_params(options))
+
+      # Add callback URL if provided
+      body[:callback_url] = options[:callback_url] if options[:callback_url]
+
+      response = @conn.post('distance-jobs') do |req|
+        req.params = { api_key: @api_key }
+        req.headers['Content-Type'] = 'application/json'
+        req.body = body.to_json
+      end
+
+      parsed = JSON.parse(response.body)
+      return parsed
+    end
+
+    # Get status of a distance matrix job
+    # @param id [String, Integer] Job ID
+    def distanceMatrixJobStatus(id)
+      response = JSON.parse(@conn.get("distance-jobs/#{id}", { api_key: @api_key }).body)
+      return response
+    end
+
+    # List all distance matrix jobs
+    # @param page [Integer] Optional page number for pagination
+    def distanceMatrixJobs(page = nil)
+      params = { api_key: @api_key }
+      params[:page] = page if page
+      response = JSON.parse(@conn.get("distance-jobs", params).body)
+      return response
+    end
+
+    # Get results of a completed distance matrix job
+    # @param id [String, Integer] Job ID
+    def getDistanceMatrixJobResults(id)
+      response = JSON.parse(@conn.get("distance-jobs/#{id}/download", { api_key: @api_key }).body)
+      return response
+    end
+
+    # Download distance matrix job results to a file
+    # @param id [String, Integer] Job ID
+    # @param file_path [String] Path to save the file
+    def downloadDistanceMatrixJob(id, file_path)
+      response = @conn.get("distance-jobs/#{id}/download", { api_key: @api_key })
+      File.write(file_path, response.body)
+      return { success: true, file_path: file_path }
+    end
+
+    # Delete a distance matrix job
+    # @param id [String, Integer] Job ID
+    def deleteDistanceMatrixJob(id)
+      response = JSON.parse(@conn.delete("distance-jobs/#{id}", { api_key: @api_key }).body)
+      return response
+    end
+
+    private
+
+    # Format a coordinate for GET requests (string format: "lat,lng" or "lat,lng,id")
+    def format_coordinate_string(coord)
+      case coord
+      when String
+        coord
+      when Array
+        if coord.length >= 3
+          "#{coord[0]},#{coord[1]},#{coord[2]}"
+        else
+          "#{coord[0]},#{coord[1]}"
+        end
+      when Hash
+        str = "#{coord[:lat]},#{coord[:lng]}"
+        str += ",#{coord[:id]}" if coord[:id]
+        str
+      else
+        raise ArgumentError, "Invalid coordinate format: #{coord.inspect}"
+      end
+    end
+
+    # Format a coordinate for POST requests (object format: {lat:, lng:, id:})
+    def format_coordinate_object(coord)
+      case coord
+      when String
+        parts = coord.split(',').map(&:strip)
+        obj = { lat: parts[0].to_f, lng: parts[1].to_f }
+        obj[:id] = parts[2] if parts[2]
+        obj
+      when Array
+        obj = { lat: coord[0].to_f, lng: coord[1].to_f }
+        obj[:id] = coord[2].to_s if coord[2]
+        obj
+      when Hash
+        obj = { lat: coord[:lat].to_f, lng: coord[:lng].to_f }
+        obj[:id] = coord[:id].to_s if coord[:id]
+        obj
+      else
+        raise ArgumentError, "Invalid coordinate format: #{coord.inspect}"
+      end
+    end
+
+    # Build distance query parameters for GET requests
+    def build_distance_params(options)
+      params = {}
+
+      # Mode (map haversine to straightline)
+      if options[:mode]
+        mode = options[:mode].to_s
+        mode = 'straightline' if mode == 'haversine'
+        params[:mode] = mode
+      end
+
+      # Units (map kilometers to km for API compatibility)
+      if options[:units]
+        units = options[:units].to_s
+        units = 'km' if units == 'kilometers'
+        params[:units] = units
+      end
+
+      params[:max_results] = options[:max_results] if options[:max_results]
+      params[:max_distance] = options[:max_distance] if options[:max_distance]
+      params[:max_duration] = options[:max_duration] if options[:max_duration]
+      params[:min_distance] = options[:min_distance] if options[:min_distance]
+      params[:min_duration] = options[:min_duration] if options[:min_duration]
+      params[:order_by] = options[:order_by].to_s if options[:order_by]
+      params[:sort] = options[:sort].to_s if options[:sort]
+
+      params
+    end
+
+    # Build distance body parameters for POST requests
+    def build_distance_body_params(options)
+      params = {}
+
+      # Mode (map haversine to straightline)
+      if options[:mode]
+        mode = options[:mode].to_s
+        mode = 'straightline' if mode == 'haversine'
+        params[:mode] = mode
+      end
+
+      # Units (map kilometers to km for API compatibility)
+      if options[:units]
+        units = options[:units].to_s
+        units = 'km' if units == 'kilometers'
+        params[:units] = units
+      end
+
+      params[:max_results] = options[:max_results] if options[:max_results]
+      params[:max_distance] = options[:max_distance] if options[:max_distance]
+      params[:max_duration] = options[:max_duration] if options[:max_duration]
+      params[:min_distance] = options[:min_distance] if options[:min_distance]
+      params[:min_duration] = options[:min_duration] if options[:min_duration]
+      params[:order_by] = options[:order_by].to_s if options[:order_by]
+      params[:sort] = options[:sort].to_s if options[:sort]
+
+      params
+    end
+
+    # Build distance query string parts for geocode/reverse requests
+    # Returns an array of query string parts to be joined with '&'
+    def build_geocode_distance_query_parts(destinations, distance_mode, distance_units, distance_options)
+      parts = []
+
+      return parts unless destinations && !destinations.empty?
+
+      # Add destinations as properly formatted array parameters
+      destinations.each do |dest|
+        parts << "destinations[]=#{URI.encode_www_form_component(format_coordinate_string(dest))}"
+      end
+
+      # Mode (map haversine to straightline)
+      if distance_mode
+        mode = distance_mode.to_s
+        mode = 'straightline' if mode == 'haversine'
+        parts << "distance_mode=#{mode}"
+      end
+
+      # Units (map kilometers to km)
+      if distance_units
+        units = distance_units.to_s
+        units = 'km' if units == 'kilometers'
+        parts << "distance_units=#{units}"
+      end
+
+      # Additional options
+      if distance_options
+        parts << "distance_max_results=#{distance_options[:max_results]}" if distance_options[:max_results]
+        parts << "distance_max_distance=#{distance_options[:max_distance]}" if distance_options[:max_distance]
+        parts << "distance_max_duration=#{distance_options[:max_duration]}" if distance_options[:max_duration]
+        parts << "distance_min_distance=#{distance_options[:min_distance]}" if distance_options[:min_distance]
+        parts << "distance_min_duration=#{distance_options[:min_duration]}" if distance_options[:min_duration]
+        parts << "distance_order_by=#{distance_options[:order_by]}" if distance_options[:order_by]
+        parts << "distance_sort=#{distance_options[:sort]}" if distance_options[:sort]
+      end
+
+      parts
+    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: geocodio-gem
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - GoldenPavilion
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-05-20 00:00:00.000000000 Z
+date: 2026-01-06 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby Gem to help you integrate your application with the Geocodio API.
 email: