Class: Geocodio::Gem

Inherits:
Object
  • Object
show all
Defined in:
lib/geocodio/gem.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key) ⇒ Gem

Returns a new instance of Gem.



14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/geocodio/gem.rb', line 14

def initialize(api_key)
  @api_key = api_key

  @conn = Faraday.new(
    url: 'https://api.geocod.io/v2/',
    headers: {'Content-Type' => 'application/json' }
  ) do |f|
    f.response :follow_redirects
    f.adapter Faraday.default_adapter
  end
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



12
13
14
 
# File 'lib/geocodio/gem.rb', line 12

def api_key
  @api_key
end

Instance Method Details

#createDistanceMatrixJob(name, origins, destinations, options = {}) ⇒ Object

Create an async distance matrix job

Parameters:

  • name (String) —

    Job name

  • origins (Array, Integer) —

    Array of coordinates or list ID

  • destinations (Array, Integer) —

    Array of coordinates or list ID

  • options (Hash) (defaults to: {}) —

    Same options as distanceMatrix() plus:

    • callback_url: URL for webhook notification

Raises:

  • (ArgumentError) 


218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/geocodio/gem.rb', line 218

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

#createList(file, filename, direction, format, callback = nil) ⇒ Object 



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/geocodio/gem.rb', line 106

def createList(file, filename, direction, format, callback = nil)
  response = @conn.post('lists') do |req|
    req.params = { 
      api_key: @api_key,
      file: file,
      filename: filename,
      direction: direction,
      format: format,
      callback: callback
    }
    req.headers['Content-Type'] = 'application/json'
  end
  parsed = JSON.parse(response.body)
  return parsed
end

#deleteDistanceMatrixJob(id) ⇒ Object

Delete a distance matrix job

Parameters:

  • id (String, Integer) —

    Job ID



289
290
291
292
 
# File 'lib/geocodio/gem.rb', line 289

def deleteDistanceMatrixJob(id)
  response = JSON.parse(@conn.delete("distance-jobs/#{id}", { api_key: @api_key }).body)
  return response
end

#deleteList(id) ⇒ Object 



142
143
144
145
 
# File 'lib/geocodio/gem.rb', line 142

def deleteList(id)
  response = JSON.parse(@conn.delete("lists/#{id}", { api_key: @api_key}).body)
  return response
end

#distance(origin, destinations, options = {}) ⇒ Object

Calculate distances from a single origin to multiple destinations

Parameters:

  • origin (String, Array, Hash) —

    Origin coordinate (“lat,lng” or “lat,lng,id” or [lat, lng] or [lat, lng, id] or lng:, id:)

  • destinations (Array) —

    Array of destination coordinates in any supported format

  • options (Hash) (defaults to: {}) —

    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

Raises:

  • (ArgumentError) 


162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/geocodio/gem.rb', line 162

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

#distanceMatrix(origins, destinations, options = {}) ⇒ Object

Calculate distance matrix from multiple origins to multiple destinations

Parameters:

  • origins (Array) —

    Array of origin coordinates

  • destinations (Array) —

    Array of destination coordinates

  • options (Hash) (defaults to: {}) —

    Same options as distance() method

Raises:

  • (ArgumentError) 


190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/geocodio/gem.rb', line 190

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

#distanceMatrixJobs(page = nil) ⇒ Object

List all distance matrix jobs

Parameters:

  • page (Integer) (defaults to: nil) —

    Optional page number for pagination



264
265
266
267
268
269
 
# File 'lib/geocodio/gem.rb', line 264

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

#distanceMatrixJobStatus(id) ⇒ Object

Get status of a distance matrix job

Parameters:

  • id (String, Integer) —

    Job ID



257
258
259
260
 
# File 'lib/geocodio/gem.rb', line 257

def distanceMatrixJobStatus(id)
  response = JSON.parse(@conn.get("distance-jobs/#{id}", { api_key: @api_key }).body)
  return response
end

#downloadDistanceMatrixJob(id, file_path) ⇒ Object

Download distance matrix job results to a file

Parameters:

  • id (String, Integer) —

    Job ID

  • file_path (String) —

    Path to save the file



281
282
283
284
285
 
# File 'lib/geocodio/gem.rb', line 281

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

#downloadList(id) ⇒ Object 



132
133
134
135
136
137
138
139
140
 
# File 'lib/geocodio/gem.rb', line 132

def downloadList(id)
  response = @conn.get("lists/#{id}/download", { api_key: @api_key})

  if (response.headers["content-type"] == "application/json")
    return JSON.parse(response.body)
  else
    return CSV.parse(response.body.force_encoding("UTF-8"))
  end
end

#geocode(query = [], fields = [], limit = nil, format = nil, destinations: nil, distance_mode: nil, distance_units: nil, distance_options: nil) ⇒ Object

Forward geocode addresses to coordinates

Parameters:

  • query (Array) (defaults to: []) —

    Array of address strings

  • fields (Array) (defaults to: []) —

    Optional fields to append (e.g., [“timezone”, “cd”])

  • limit (Integer) (defaults to: nil) —

    Maximum number of results

  • format (String) (defaults to: nil) —

    Response format (“simple” for simplified response)

  • destinations (Array) (defaults to: nil) —

    Optional array of destination coordinates for distance calculation

  • distance_mode (Symbol) (defaults to: nil) —

    Distance mode (:straightline, :driving, :haversine)

  • distance_units (Symbol) (defaults to: nil) —

    Distance units (:miles, :kilometers)

  • distance_options (Hash) (defaults to: nil) —

    Additional distance options (max_results, max_distance, etc.)



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/geocodio/gem.rb', line 35

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
    # 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|
      req.params = { fields: fields.join(","), limit: limit, api_key: @api_key }
      req.headers['Content-Type'] = 'application/json'
      req.body = query.to_json
    end
    parsed = JSON.parse(response.body)
    return parsed
  end
end

#getAllLists ⇒ Object 



127
128
129
130
 
# File 'lib/geocodio/gem.rb', line 127

def getAllLists
  response = JSON.parse(@conn.get("lists", { api_key: @api_key}).body)
  return response
end

#getDistanceMatrixJobResults(id) ⇒ Object

Get results of a completed distance matrix job

Parameters:

  • id (String, Integer) —

    Job ID



273
274
275
276
 
# File 'lib/geocodio/gem.rb', line 273

def getDistanceMatrixJobResults(id)
  response = JSON.parse(@conn.get("distance-jobs/#{id}/download", { api_key: @api_key }).body)
  return response
end

#getList(id) ⇒ Object 



122
123
124
125
 
# File 'lib/geocodio/gem.rb', line 122

def getList(id)
  response = JSON.parse(@conn.get("lists/#{id}", { api_key: @api_key }).body)
  return response
end

#reverse(query = [], fields = [], limit = nil, format = nil, destinations: nil, distance_mode: nil, distance_units: nil, distance_options: nil) ⇒ Object

Reverse geocode coordinates to addresses

Parameters:

  • query (Array) (defaults to: []) —

    Array of coordinate strings (“lat,lng”)

  • fields (Array) (defaults to: []) —

    Optional fields to append (e.g., [“timezone”, “cd”])

  • limit (Integer) (defaults to: nil) —

    Maximum number of results

  • format (String) (defaults to: nil) —

    Response format (“simple” for simplified response)

  • destinations (Array) (defaults to: nil) —

    Optional array of destination coordinates for distance calculation

  • distance_mode (Symbol) (defaults to: nil) —

    Distance mode (:straightline, :driving, :haversine)

  • distance_units (Symbol) (defaults to: nil) —

    Distance units (:miles, :kilometers)

  • distance_options (Hash) (defaults to: nil) —

    Additional distance options (max_results, max_distance, etc.)



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/geocodio/gem.rb', line 75

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
    # 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|
      req.params = { fields: fields.join(","), limit: limit, api_key: @api_key }
      req.headers['Content-Type'] = 'application/json'
      req.body = query.to_json
    end
    parsed = JSON.parse(response.body)
    return parsed
  end
end