michaeldwan-urban-mapping-api

= 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 http://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"...

== Helpful Links

• urban-mapping-api Gem documentation http://rdoc.info/projects/michaeldwan/urban-mapping-api
• Urban Mapping http://www.urbanmapping.com/urbanware/neighborhood-database/index.html
• Api Documentation http://developer.urbanmapping.com/docs/neighborhoods
• Register for a free API key http://developer.urbanmapping.com/accounts/register

== 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

Copyright (c) 2009 Michael Dwan. See LICENSE for details.