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