T Rex: Consume Metasaurus

The t_rex gem consumes the Metasaurus geographic lookup service. Roar!

Setup

require 't_rex'

Usage

To use the gem, create and transmit a TRex::Request. The general form is …

request = TRex::Request.new(options, headers)
response = request.get

… where options and headers are both hashes. Both arguments are optional.

You can also pass a block to .get to process the response.

request = TRex::Request.new(options, headers)
request.get do |response|
  # do something with the response
end

trex also provides a convenience method to build and transmit the request at once.

response = TRex::Request.get(options, headers)

This form can also take a block.

TRex::Request.get(options, headers) do |response|
  # do something with the response
end

Which form to use is a matter of style. The second form is provided for brevity. Both allow you to add a geolocation header to the request before it is sent, albeit with slightly different code.

The next sections describe each of the available requests.

Ping Metasaurus

The simplest request pings Metasaurus.

request = TRex::Request.new
request.get

# produces
# {status: 0}

Lookup via Zipcode

To receive information about a zipcode, send it as an argument in the options hash.

response = TRex::Request.get({zip: 27605})

# produces
# {}

If you pass a 5+4 zipcode as a string, the "+4" portion is stripped prior to calling Metasaurus.

Lookup via Latitude and Longitude

You can also perform a lookup with latitude and longitude.

response = TRex::Request.get({lat: -35, lng: 79})

# produces
# {}

Lookup via City and State

The most typical lookup uses city and state name. (The state name must be spelled out. Two-letter abbreviations produce incorrect results.)

response = TRex::Request.get({city: 'Atlanta', state: 'Georgia'})

# produces
# {}

Hitting Other Metasaurus Endpoints

By default, requests from T Rex hit the /geo endpoint. However, you can hit other service endpoints, such as /nearby_neighborhoods, if you specify the :endpoint option.

request = TRex::Request.get({
  endpoint: :nearby_neighborhood,
  city: 'Atlanta',
  state: 'Georgia'})

# produces
# {}

Valid endpoints are :colleges, :community, :geo, military_bases, nearby_neighborhoods, nearby_colleges, nearby_military_bases.

Add a Geolocation Header

If you cannot provide a zipcode, latitude/longitude pair, or a city and state, you can approximate a location using the Geo IP information sent from the browser (if available).

There are three forms. In the first, you can set the location using a setter method.

request = TRex::Request.new
request.location = 'city=Norcross,region=GA,country=US,' \
  'lat=33.9411,long=-84.2136,metro=909,msa=9009,' \
  'zip=30092,areacode=770'
response = request.get

# produces
# {}

Or, in the second method, you can pass the location in the headers hash.

headers = { 'X-Geo-Data' => 'city=Norcross,region=GA,country=US,…' }
request = TRex::Request.new({}, headers)
request.get

# produces
# {}

And the third is similar to the second, but is terse.

headers = { 'X-Geo-Data' => 'city=Norcross,region=GA,country=US,…' }
response = TRex::Request.get({}, headers)

# produces
# {}

If you do not have a location string, you can set the location to Norcross, GA, with set_default_location.

request = TRex::Request.new
request.set_default_location
response = request.get

# produces
# {}

-- Thanks for reading! Here's a cool factoid to reward your effort.