Class: Tenka::Client

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

Overview

The main class for the client. TODO: Provide usage examples here.

Constant Summary collapse

DefaultOpts =

The defaults when initializing a client. ‘host` specifies the hostname to connect to. You probably won’t need to change this. ‘ssl` turns HTTPS on or off. If you are using an API key, you probably want to leave it on. `port` specifies the port to connect to.

{
	host: 'api.tenka.io',
	port: 443,
	ssl: true,
	api_key: nil,
}.freeze
Units =

For endpoints that require units to be specified, this is the list of units.

Set.new %w(
	mile
	km
)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}) ⇒ Client

Creates a new client. To simplify the API, the client carries information in the form of state, and thus is not thread-safe; you should instantiate one client per thread that accesses Tenka.



44
45
46
47
48
49
50
51
52
 
# File 'lib/tenka.rb', line 44

def initialize opts = {}
	self.opts = DefaultOpts.merge(opts)

	# If they don't specify a port but they do turn off SSL, we set
	# the port to 80.
	if !opts.has_key?(port) && !ssl
		self.opts[:port] = 80
	end
end

Instance Attribute Details

#api_tokens_left ⇒ Object

Returns the value of attribute api_tokens_left.



36
37
38
 
# File 'lib/tenka.rb', line 36

def api_tokens_left
  @api_tokens_left
end

#last_error ⇒ Object

Returns the value of attribute last_error.



36
37
38
 
# File 'lib/tenka.rb', line 36

def last_error
  @last_error
end

#last_resp ⇒ Object

Returns the value of attribute last_resp.



36
37
38
 
# File 'lib/tenka.rb', line 36

def last_resp
  @last_resp
end

#opts ⇒ Object

Returns the value of attribute opts.



36
37
38
 
# File 'lib/tenka.rb', line 36

def opts
  @opts
end

#rate_limit_calls_left ⇒ Object

Returns the value of attribute rate_limit_calls_left.



36
37
38
 
# File 'lib/tenka.rb', line 36

def rate_limit_calls_left
  @rate_limit_calls_left
end

Instance Method Details

#calls_left ⇒ Object

Returns the number of calls your API token has left, as well as how many calls you can make before you hit the rate limit for the server.

This information is automatically gathered (whether your API key is valid or not) on every request, so you can also just check Tenka::Client#rate_limit_calls_left and Tenka::Client#api_tokens_left.

Making a request against this endpoint does not reduce the number of API tokens you have left. (It does count towards the rate limit.)

A 404 from this endpoint indicates that your API key is invalid.



118
119
120
121
122
123
124
 
# File 'lib/tenka.rb', line 118

def calls_left
	ok, body = get('/tokens-remaining')
	ok && {
		rate_limit: rate_limit_calls_left,
		api_limit: api_tokens_left,
	}
end

#containing_lat_long(lat, long) ⇒ Object Also known as: containing_lat_lon

Reverse-geocode a latitude/longitude pair.



70
71
72
73
 
# File 'lib/tenka.rb', line 70

def containing_lat_long lat, long
	ok, body = get('/containing/lat-long', lat: lat, long: long)
	ok && body
end

#containing_zip(zip) ⇒ Object

Reverse-geocode a ZIP code centroid. (Tenka only supports US ZIPs for now, but this is not enforced client-side.)

Note that ZIP codes often describe very odd shapes; they are based on postal service routes rather than geographical boundaries. As a result, the centroid may lie in a different city than any single point within the actual boundaries of the ZIP code. (ZIP centroids are popular because of their granularity, but they should be used with caution.)

ZIP codes can start with leading zeroes. It is advised to use a string to represent a ZIP code rather than an integer.



88
89
90
91
 
# File 'lib/tenka.rb', line 88

def containing_zip zip
	ok, body = get('/containing/zip', zip: zip)
	ok && body
end

#nearby_zip(zip, radius, units = 'mile') ⇒ Object

Returns a list of ZIP codes whose centroids are within a given radius of another ZIP code’s centroid. (See the remarks about centroids in #containing_zip.)



96
97
98
99
100
101
102
103
104
 
# File 'lib/tenka.rb', line 96

def nearby_zip zip, radius, units = 'mile'
	unless Units.include?(units)
		raise ArgumentError, "Invalid unit #{units}.  Must be one "\
			"of #{Units.to_a.join(', ')}."
	end
	ok, body = get('/nearby/zip',
		zip: zip, radius: radius, units: units)
	ok && body['zips']
end