urban-mapping-api

A simple ruby interface to Urban Mapping’s free and premium neighborhood lookup API.

Installation

sudo gem install michaeldwan-urban-mapping-api

Gem dependencies:

  • curb

  • json

Examples

To get started you need to require ‘urban-mapping-api’:

% irb -rubygems
irb(main):001:0> require 'urban-mapping-api'
# => true

Before you do anything, create an instance of UrbanMapping::Interface

interface = UrbanMapping::Interface.new('my-api-key')

For premium API access, include the premium API key

interface = UrbanMapping::Interface.new('my-api-key', :shared_secret => 'my-shared-secred')
interface.premium_api? 
# => true

The default return value of all methods is an OpenStruct or array of OpenStructs.

interface = UrbanMapping::Interface.new('my-api-key')
hood = interface.get_neighborhood_detail(3094847)
hood
# => #<OpenStruct city="Chicago", name="The Loop", state="IL", ...>
hood.city
# => "Chicago"

If you want the raw hash output, pass :raw => true to the constructor

interface = UrbanMapping::Interface.new('my-api-key', :shared_secret => 'my-shared-secred', :raw => true)
hood = interface.get_neighborhood_detail(3094847)
hood
# => {"wkt_centroid"=>"POINT(-87.6260772332496 41.8782770670931)", "name"=>"The Loop", "city"=>"Chicago"...
hood.city
# => "Chicago"

(If you don’t have an api key, go get one at developer.urbanmapping.com/accounts/register/)

Now that you have an instance of the interface, you can make calls to the service. (The below examples are using raw output.)

interface.get_neighborhoods_by_postal_code('60654')
# => [{"name"=>"River North", "city"=>"Chicago", "country"=>"USA", "id"=>3320072, "state"=>"IL"}, ...]

interface.get_neighborhoods_by_lat_lng(41.882088, -87.624454)
# => [{"name"=>"The Loop", "city"=>"Chicago", "country"=>"USA", "id"=>3094847, "state"=>"IL"}]

interface.get_neighborhood_detail(3094847)
# => {"wkt_centroid"=>"POINT(-87.6260772332496 41.8782770670931)", "name"=>"The Loop", "city"=>"Chicago"...

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Copyright © 2009 Michael Dwan. See LICENSE for details.