Class: Geocodio::Client

Inherits:
Object
  • Object
show all
Includes:
Utils
Defined in:
lib/geocodio/client.rb,
lib/geocodio/client/error.rb,
lib/geocodio/client/response.rb

Defined Under Namespace

Classes: Error, Response

Constant Summary collapse

CONTENT_TYPE =
'application/json'
METHODS =
{
  :get    => Net::HTTP::Get,
  :post   => Net::HTTP::Post,
  :put    => Net::HTTP::Put,
  :delete => Net::HTTP::Delete
}
HOST =
'api.geocod.io'
BASE_PATH =
'/v1.2'
PORT =
80

Instance Method Summary collapse

Methods included from Utils

#normalize_coordinates, #normalize_params_and_options, #parse_nested_results, #parse_results

Constructor Details

#initialize(api_key = ENV['GEOCODIO_API_KEY']) ⇒ Client

Returns a new instance of Client.


24
25
26
# File 'lib/geocodio/client.rb', line 24

def initialize(api_key = ENV['GEOCODIO_API_KEY'])
  @api_key = api_key
end

Instance Method Details

#geocode(addresses, options = {}) ⇒ Geocodio::Address, Array<Geocodio::AddressSet>

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.

Parameters:

  • addresses (Array<String>)

    one or more String addresses

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

    an options hash

Options Hash (options):

  • :fields (Array)

    a list of option fields to request (possible: “cd” or “cd113”, “stateleg”, “school”, “timezone”)

Returns:


36
37
38
39
40
41
42
43
44
# 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 = {}) ⇒ Geocodio::Address

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.

Parameters:

  • address (String)

    the full or partial address to parse

Returns:


75
76
77
78
79
80
# 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_geocode(coordinates, options = {}) ⇒ Geocodio::Address, Array<Geocodio::AddressSet> Also known as: reverse

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.

Parameters:

  • coordinates (Array<String>, Array<Hash>)

    one or more pairs of coordinates

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

    an options hash

Options Hash (options):

  • :fields (Array)

    a list of option fields to request (possible: “cd” or “cd113”, “stateleg”, “school”, “timezone”)

Returns:


57
58
59
60
61
62
63
64
65
# 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