class Geocodio::Client

Constants

BASE_PATH
CONTENT_TYPE
HOST
METHODS
PORT

Public Class Methods

new(api_key = ENV['GEOCODIO_API_KEY']) click to toggle source
# File lib/geocodio/client.rb, line 24
def initialize(api_key = ENV['GEOCODIO_API_KEY'])
  @api_key = api_key
end

Public Instance Methods

geocode(addresses, options = {}) click to toggle source

Geocodes one or more addresses. If one address is specified, a GET request is submitted to api.geocod.io/v1/geocode. Multiple addresses will instead submit a POST request.

@param [Array<String>] addresses one or more String addresses @param [Hash] options an options hash @option options [Array] :fields a list of option fields to request (possible: “cd” or “cd113”, “stateleg”, “school”, “timezone”) @return [Geocodio::Address, Array<Geocodio::AddressSet>] One or more Address Sets

# File lib/geocodio/client.rb, line 36
def geocode(addresses, options = {})
  if addresses.size < 1
    raise ArgumentError, 'You must provide at least one address to geocode.'
  elsif addresses.size == 1
    geocode_single(addresses.first, options)
  else
    geocode_batch(addresses, options)
  end
end
parse(address, options = {}) click to toggle source

Sends a GET request to api.geocod.io/v1/parse to correctly dissect an address into individual parts. As this endpoint does not do any geocoding, parts missing from the passed address will be missing from the result.

@param address [String] the full or partial address to parse @return [Geocodio::Address] a parsed and formatted Address

# File lib/geocodio/client.rb, line 75
def parse(address, options = {})
  params, options = normalize_params_and_options(options)
  params[:q] = address

  Address.new get('/parse', params, options).body
end
reverse(coordinates, options = {})
Alias for: reverse_geocode
reverse_geocode(coordinates, options = {}) click to toggle source

Reverse geocodes one or more pairs of coordinates. Coordinate pairs may be specified either as a comma-separated “latitude,longitude” string, or as a Hash with :lat/:latitude and :lng/:longitude keys. If one pair of coordinates is specified, a GET request is submitted to api.geocod.io/v1/reverse. Multiple pairs of coordinates will instead submit a POST request.

@param [Array<String>, Array<Hash>] coordinates one or more pairs of coordinates @param [Hash] options an options hash @option options [Array] :fields a list of option fields to request (possible: “cd” or “cd113”, “stateleg”, “school”, “timezone”) @return [Geocodio::Address, Array<Geocodio::AddressSet>] One or more Address Sets

# File lib/geocodio/client.rb, line 57
def reverse_geocode(coordinates, options = {})
  if coordinates.size < 1
    raise ArgumentError, 'You must provide coordinates to reverse geocode.'
  elsif coordinates.size == 1
    reverse_geocode_single(coordinates.first, options)
  else
    reverse_geocode_batch(coordinates, options)
  end
end
Also aliased as: reverse

Private Instance Methods

geocode_batch(addresses, options = {}) click to toggle source
# File lib/geocodio/client.rb, line 111
def geocode_batch(addresses, options = {})
  params, options = normalize_params_and_options(options)
  options[:body] = addresses

  response = post '/geocode', params, options

  parse_nested_results(response)
end
geocode_single(address, options = {}) click to toggle source
# File lib/geocodio/client.rb, line 90
def geocode_single(address, options = {})
  params, options = normalize_params_and_options(options)
  params[:q] = address

  response  = get '/geocode', params, options
  addresses, input = parse_results(response)

  AddressSet.new(address, *addresses, input: input)
end
request(method, path, options) click to toggle source
# File lib/geocodio/client.rb, line 129
def request(method, path, options)
  path += "?api_key=#{@api_key}"

  if params = options[:params] and !params.empty?
    q = params.map { |k, v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }
    path += "&#{q.join('&')}"
  end

  req = METHODS[method].new(BASE_PATH + path, 'Accept' => CONTENT_TYPE)

  if options.key?(:body)
    req['Content-Type'] = CONTENT_TYPE
    req.body = options[:body] ? JSON.dump(options[:body]) : ''
  end

  http = Net::HTTP.new HOST, PORT
  http.read_timeout = options[:timeout] if options[:timeout]
  res  = http.start { http.request(req) }

  case res
  when Net::HTTPSuccess
    return Response.new(res)
  else
    raise Error, res
  end
end
reverse_geocode_batch(pairs, options = {}) click to toggle source
# File lib/geocodio/client.rb, line 120
def reverse_geocode_batch(pairs, options = {})
  params, options = normalize_params_and_options(options)
  options[:body] = pairs.map { |pair| normalize_coordinates(pair) }

  response = post '/reverse', params, options

  parse_nested_results(response)
end
reverse_geocode_single(pair, options = {}) click to toggle source
# File lib/geocodio/client.rb, line 100
def reverse_geocode_single(pair, options = {})
  params, options = normalize_params_and_options(options)
  pair = normalize_coordinates(pair)
  params[:q] = pair

  response  = get '/reverse', params, options
  addresses, input = parse_results(response)

  AddressSet.new(pair, *addresses, input: input)
end