DCGOV 0.0.1

data/LICENSE

@@ -0,0 +1,21 @@
+== DC311
+
+Copyright (c) 2009 Zvi Band and skeevisArts LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,29 @@
+= DC Government GeoCoder and 311 API
+
+... a ruby gem for the not-yet-complete API published by the DC OCTO
+
+== Install
+
+sudo gem install dcgov
+
+== Example
+
+Here's a quick example of how you could use it.
+
+    require 'rubygems'
+    require 'dcgov'
+    results = DCGOV::GeoCoder.get({:address=>"441 4th str, nw"})
+    print results.inspect
+
+== Usage
+
+Honestly, I haven't had a chance yet. But I will say this. If you go into the spec directory you'll find tests for the geocoder and open_311 APIs.
+The rspec tests
+
+If you feel like helping out, expand this readme for me :-)
+
+Zvi Band, 2009
+zvi@skeevisarts.com
+http://skeevisarts.com
+
+@skeevis on the twitter.

data/Rakefile

@@ -0,0 +1,52 @@
+# 
+# To change this template, choose Tools | Templates
+# and open the template in the editor.
+ 
+
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'spec/rake/spectask'
+
+spec = Gem::Specification.new do |s|
+  s.name = 'DCGOV'
+  s.version = '0.0.1'
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README', 'LICENSE']
+  s.summary = 'A basic interface to the citywide API published by the District of Columbia'
+  s.description = s.summary
+  s.author = 'Zvi Band'
+  s.email = 'zvi@skeevisarts.com'
+  s.homepage = 'http://skeevisarts.com'
+  # s.executables = ['your_executable_here']
+  s.files = %w(LICENSE README Rakefile) + Dir.glob("{bin,lib,spec}/**/*")
+  s.require_path = "lib"
+  s.bindir = "bin"
+  s.add_dependency("json")
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  files =['README', 'LICENSE', 'lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README" # page to start on
+  rdoc.title = "DCGOV Docs"
+  rdoc.rdoc_dir = 'doc/rdoc' # rdoc output folder
+  rdoc.options << '--line-numbers'
+end
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*.rb']
+end
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+end

data/lib/dcgov.rb

@@ -0,0 +1,19 @@
+require 'uri'
+require 'cgi'
+require 'net/http'
+require 'rubygems'
+require 'json'
+
+$:.unshift(File.dirname(__FILE__))
+require 'dcgov/easy_class_maker'
+require 'dcgov/geocoder'
+require 'dcgov/open311'
+require 'dcgov/service_request_field'
+require 'dcgov/service_type'
+require 'dcgov/address'
+require 'dcgov/util'
+
+module DCGOV
+   #Not too much in here...
+
+end

data/lib/dcgov/address.rb

@@ -0,0 +1,48 @@
+module DCGOV
+  class Address
+    include EasyClassMaker
+
+    #    just a sample of what dc returns, for reference purposes. 
+    #    [{"aid"=>"285552"}, {"status"=>"ACTIVE"}, {"fulladdress"=>"441 4TH STREET NW"}, {"addrnum"=>"441"}, {"stname"=>"4TH"}, {"street_type"=>"STREET"},
+    #      {"quadrant"=>"NW"}, {"city"=>"WASHINGTON"}, {"state"=>"DC"}, {"xcoord"=>"398642.18"}, {"ycoord"=>"136399.84"},
+    #      {"ssl"=>"0532    0020"}, {"anc"=>"ANC 6C"}, {"psa"=>"Police Service Area 101"}, {"ward"=>"Ward 6"}, {"nbhd_action"=>" "},
+    #      {"cluster"=>"Cluster 8"}, {"poldist"=>"Police District - First District"}, {"roc"=>"-"}, {"census_tract"=>"59"},
+    #      {"vote_prcnct"=>"Precinct 143"}, {"smd"=>"SMD02 6C09"}, {"zipcode"=>"20001"}, {"latitude"=>"38.89544591"},
+    #      {"longitude"=>"-77.01565221"}, {"distance"=>"0"}]
+
+    attributes  :aid,:status,:fulladdress,:addrnum,:stname,:street_type,:quadrant,:city,:state,:xoord,:ycoord,:ssl,:anc,:psa,:ward,:nbhd,:clust,:poldist,:roc,:census_tract,
+      :vote_prcnct,:smd,:zipcode,:latitude,:longitude,:distance
+
+    # Creates a new user from a piece of xml
+    def self.new_from_hash(hsh)
+      u = new
+      u.aid = hsh['aid']
+      u.status = hsh['status']
+      u.fulladdress = hsh['fulladdress']
+      u.addrnum = hsh['addrnum']
+      u.stname = hsh['stname']
+      u.street_type = hsh['street_type']
+      u.quadrant = hsh['quadrant']
+      u.city = hsh['city']
+      u.state = hsh['state']
+      u.xoord = hsh['xoord']
+      u.ycoord = hsh['ycoord']
+      u.ssl = hsh['ssl']
+      u.anc = hsh['anc']
+      u.psa = hsh['psa']
+      u.ward = hsh['ward']
+      u.nbhd = hsh['nbhd']
+      u.clust = hsh['clust']
+      u.poldist = hsh['poldist']
+      u.roc = hsh['roc']
+      u.census_tract = hsh['census_tract']
+      u.vote_prcnct = hsh['vote_prcnct']
+      u.smd = hsh['smd']
+      u.zipcode = hsh['zipcode']
+      u.latitude = hsh['latitude']
+      u.longitude = hsh['longitude']
+      u.distance = hsh['distance']
+      u
+    end
+  end
+end

data/lib/dcgov/easy_class_maker.rb

@@ -0,0 +1,45 @@
+# This is pretty much just a macro for creating a class that allows
+# using a block to initialize stuff and to define getters and setters
+# really quickly.
+#
+# I stole this from the Twitter gem. Who knows who they stole it from.
+module DCGOV
+  module EasyClassMaker
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # creates the attributes class variable and creates each attribute's accessor methods
+      def attributes(*attrs)
+        @@attributes = attrs
+        @@attributes.each { |a| attr_accessor a }
+      end
+
+      # read method for attributes class variable
+      def self.attributes; @@attributes end
+    end
+
+    # allows for any class that includes this to use a block to initialize
+    # variables instead of assigning each one seperately
+    #
+    # Example:
+    #
+    # instead of...
+    #
+    # s = Status.new
+    # s.foo = 'thing'
+    # s.bar = 'another thing'
+    #
+    # you can ...
+    #
+    # Status.new do |s|
+    #   s.foo = 'thing'
+    #   s.bar = 'another thing'
+    # end
+    def initialize
+      yield self if block_given?
+    end
+  end
+end

data/lib/dcgov/geocoder.rb

@@ -0,0 +1,60 @@
+module DCGOV
+  class GeoCoder
+    #master dispatcher
+    def self.get(options)
+      if options[:address]
+        find_by_address(options[:address])
+      elsif options[:lat] && options[:lon]
+        find_by_lat_lon(options[:lat],options[:lon])
+      elsif options[:mar_id]
+        find_by_id(options[:mar_id])
+      else
+        nil #dumbass.
+      end
+    end
+
+
+    #do a search via latitude and longitude.
+    def self.find_by_lat_lon(lat,lon)
+       begin
+        request_url =  "/geocoding/v1/getFromLatLong.json?lat=#{CGI::escape(lat)}&long=#{CGI::escape(lon)}"
+        result_json = DCGOV::Util.pull_from_json(request_url)
+        return result_json["addresses"].collect { |address| DCGOV::Address.new_from_hash(address["address"][0])  }
+      rescue
+        #crap, something went wrong
+        return nil
+      end
+    end
+
+
+    #find via a normal street address... "1600 pennsylvania"
+    def self.find_by_address(address)
+       begin
+        request_url =  "/geocoding/v1/search.json?address=#{CGI::escape(address)}"
+        result_json = DCGOV::Util.pull_from_json(request_url)
+        return result_json["addresses"].collect { |address| DCGOV::Address.new_from_hash(address["address"][0])  }
+      rescue
+        #crap, something went wrong
+        return nil
+      end
+    end
+
+    #find by a mar ID
+    def self.find_by_id(mar_id)
+      begin
+        request_url =  "/geocoding/v1/get.json?aid=#{mar_id}"
+        result_json = DCGOV::Util.pull_from_json(request_url)
+        return DCGOV::Address.new_from_hash(result_json["address"][0])
+      rescue
+        #crap, something went wrong
+        return nil
+      end
+    end
+
+    # just so I could make sure rspec was working.
+    def self.foo
+      "bar"
+    end
+    
+  end
+end

data/lib/dcgov/open311.rb

@@ -0,0 +1,36 @@
+module DCGOV
+  class Open311
+    def self.get_service_types()
+      request_url = "/open311/v1/meta_getTypesList.json"
+      result_json = DCGOV::Util.pull_from_json(request_url)
+      return result_json["servicetypeslist"].collect { |st| DCGOV::ServiceType.new_from_hash(st["servicetype"])  }
+    end
+
+    def self.get_request_fields(sr_id)
+      request_url = "/open311/v1/meta_getTypeDefinition.json?servicecode=#{CGI::escape(sr_id)}"
+      result_json = DCGOV::Util.pull_from_json(request_url)
+      #print result_json.inspect
+      return result_json["servicetypedefinition"].collect { |st| DCGOV::ServiceRequestField.new_from_hash(st["servicetype"])  }
+    end
+
+    def self.get(request_id)
+      request_url = "/open311/v1/get.json?servicerequestid=#{CGI::escape(request_id)}"
+      result_json = DCGOV::Util.pull_from_json(request_url)
+      results_fixed =  DCGOV::Util::fix_hash(result_json["servicerequest"])
+      return results_fixed
+    end
+
+    def self.resolve_token(token_id)
+      request_url = "/open311/v1/getFromToken.json?token=#{token_id}"
+      result_json = DCGOV::Util.pull_from_json(request_url)
+      result_json["servicerequestid"]
+    end
+
+    def self.submit(values)
+      request_url = "/open311/v1/submit.json"
+      result_json = DCGOV::Util.post_to_json(values,request_url)
+      result_json["token"]
+    end
+
+  end
+end

data/lib/dcgov/service_request.rb

@@ -0,0 +1,40 @@
+module DCGOV
+  class ServiceRequest
+
+ include EasyClassMaker
+ 
+    attributes  :anc,:lattitude,:serviceorderdate,:resolution,:servicerequestid,:siteaddress,:serviceorderstatus,:district,:zipcode,:servicenotes,:servicetypecodedescription,:servicecodedescription,:servicecode,:neighborhoodcluster,:servicepriority,:aid,:serviceduedate,:resolutiondate,:psa,:longitude,:smd,:ward,:agencyabbreviation,:servicetypeocde
+    
+    # Creates a new user from a piece of xml
+    def self.new_from_hash(hsh)
+      u = new
+      u.anc = hsh['anc']
+      u.lattitude = hsh['lattitude']
+      u.serviceorderdate = hsh['serviceorderdate']
+      u.resolution = hsh['resolution']
+      u.servicerequestid = hsh['servicerequestid']
+      u.siteaddress = hsh['siteaddress']
+      u.serviceorderstatus = hsh['serviceorderstatus']
+      u.district = hsh['district']
+      u.zipcode = hsh['zipcode']
+      u.servicenotes = hsh['servicenotes']
+      u.servicetypecodedescription = hsh['servicetypecodedescription']
+      u.servicecodedescription = hsh['servicecodedescription']
+      u.servicecode = hsh['servicecode']
+      u.neighborhoodcluster = hsh['neighborhoodcluster']
+      u.servicepriority = hsh['servicepriority']
+      u.aid = hsh['aid']
+      u.serviceduedate = hsh['serviceduedate']
+      u.resolutiondate = hsh['resolutiondate']
+      u.psa = hsh['psa']
+      u.longitude = hsh['longitude']
+      u.smd = hsh['smd']
+      u.ward = hsh['ward']
+      u.agencyabbreviation = hsh['agencyabbreviation']
+      u.servicetypeocde = hsh['servicetypeocde']
+
+
+      u
+    end
+  end
+end

data/lib/dcgov/service_request_field.rb

@@ -0,0 +1,25 @@
+module DCGOV
+  class ServiceRequestField
+    include EasyClassMaker
+    #{"servicetype"=>[{"servicetype"=>"Abandoned Bicycles"}, {"servicecode"=>"S0021"},
+    #{"name"=>"ABDBIC-HOWLONG"}, {"prompt"=>"How long has the bicycle been abandoned?"},
+    # {"required"=>"Y"}, {"type"=>"TextBox           "}, {"width"=>"200"}, {"itemlist"=>"\r"}]}
+
+    attributes  :service_type,:service_code,:field_name,:field_label,:field_required,:field_type,:field_width,:item_list
+
+    # Creates a new user from a piece of xml
+    def self.new_from_hash(hsh)
+      u = new
+      u.service_type = hsh[0]['servicetype']
+      u.service_code = hsh[1]['servicecode']
+      u.field_name = hsh[2]['name']
+      u.field_label = hsh[3]['prompt']
+      u.field_required = hsh[4]['required']
+      u.field_type = hsh[5]['type']
+      u.field_width = hsh[6]['width']
+      u.item_list = hsh[7]['itemlist']
+      u
+    end
+
+  end
+end

data/lib/dcgov/service_type.rb

@@ -0,0 +1,16 @@
+module DCGOV
+  class ServiceType
+    include EasyClassMaker
+    attributes  :service_type,:service_code
+
+    # Creates a new user from a piece of xml
+    def self.new_from_hash(hsh)
+      hash_to_proc = hsh.to_a
+      u = new
+      u.service_type = hash_to_proc[0]['servicetype']
+      u.service_code = hash_to_proc[1]['servicecode']
+      u
+    end
+
+  end
+end

data/lib/dcgov/util.rb

@@ -0,0 +1,42 @@
+module DCGOV
+  class Util
+
+    # just about all there is.
+    def self.pull_from_json(params)
+
+      #why am I wrapping the entire deal in a rescue block? Well, the API has no error handling at all
+      # so if you enter in something bad, it just craps on you.
+      begin
+        @resp
+        Net::HTTP.start('api.dc.gov') {|http|
+          req = Net::HTTP::Get.new(params)
+          response = http.request(req)
+          @resp = response.body
+        }
+        JSON.parse @resp
+      rescue
+        #so the caller can catch a "better" error than some JSON parsing or HTTP bs.
+        raise "An error occurred while attempting to grab and parse the results"
+      end
+    end
+
+    def self.post_to_json(params,url)
+      @resp
+      Net::HTTP.start('api.dc.gov') {|http|
+        req = Net::HTTP::Post.new(url)
+        req.set_form_data(params)
+        response = http.request(req)
+        @resp = response.body
+      }
+      JSON.parse @resp
+    end
+
+    def self.fix_hash(hsh)
+      results = Hash.new
+      hsh.each { |i|
+        results.merge!(i)
+      }
+      return results
+    end
+  end
+end

data/spec/geocoder_spec.rb

@@ -0,0 +1,42 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe "DCGOV::GeoCoder" do
+
+  it "should be able to look up an address that exists" do
+    results = DCGOV::GeoCoder.get({:address=>"441 4th str, nw"})
+    results.length.should == 1
+  end
+
+  it "should be able to look up an address that doesn't exist" do
+    results = DCGOV::GeoCoder.get({:address=>"1dsggdsdgssdgdsgdsgdsgdgsW"})
+    results.length.should == 0
+  end
+
+  it "should be able to look up an address that has multiple results" do
+    results = DCGOV::GeoCoder.get({:address=>"441 4th str"})
+    results.length.should == 2
+  end
+
+  it "should be able to look up a latitude and a longitude" do
+    results = DCGOV::GeoCoder.get({:lat=>"38.89544591",:lon=>"-77.01565221"})
+    results[0].aid.should=="285552"
+    results.length.should > 0
+  end
+
+  it "should be able to look up via a mar ID" do
+    aid = 285552
+    result = DCGOV::GeoCoder.get({:mar_id=>aid})
+    result.aid.to_i.should == aid
+  end
+
+  it "should return nil when a nonsensical mar is thrown" do
+    results = DCGOV::GeoCoder.get({:mar_id=>'adslkfhjdgsalkjgdlksdgjlgkds'})
+    results.should == nil
+  end
+
+  #stupid test. for fun.
+  it "should work" do
+    DCGOV::GeoCoder.foo.should == "bar"
+  end
+  
+end

data/spec/open_311_spec.rb

@@ -0,0 +1,41 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe "DCGOV::Open311" do
+
+  it "should return a list of service types" do
+    service_types = DCGOV::Open311.get_service_types()
+    service_types.length.should > 0
+    service_types[0].class.to_s.should == "DCGOV::ServiceType"
+    service_types[0].service_type.should =="Abandoned Bicycles"
+    service_types[0].service_code.should =="S0021"
+  end
+
+  it "should return a list of fields for a service type" do
+    service_code="S0021"
+    request_fields = DCGOV::Open311.get_request_fields(service_code)
+    request_fields.length.should > 0
+    request_fields[0].service_type.should == "Abandoned Bicycles"
+    request_fields[0].field_name.should == "ABDBIC-HOWLONG"
+    request_fields[0].field_label.should == "How long has the bicycle been abandoned?"
+
+  end
+
+  it "should return a request based on a service ID" do
+    request_id="123456"
+    request = DCGOV::Open311.get(request_id)
+    request.class.to_s.should == "Hash"
+  end
+
+  it "should convert a token into a service request id" do
+    token_id = "123456"
+    service_request_id = DCGOV::Open311.resolve_token(token_id)
+    service_request_id.should_not == nil
+  end
+
+  it "should post a service request" do
+    values = Hash.new
+    token_id = DCGOV::Open311.submit(values)
+    token_id.should_not == nil
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems'
+  gem 'rspec'
+  require 'spec'
+end
+
+dir = File.dirname(__FILE__)
+
+$:.unshift(File.join(dir, '/../lib/'))
+require dir + '/../lib/dcgov'
+
+
+def stdout_for(&block)
+  # Inspired by http://www.ruby-forum.com/topic/58647
+  old_stdout = $stdout
+  $stdout = StringIO.new
+  yield
+  output = $stdout.string
+  $stdout = old_stdout
+  output
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: DCGOV
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Zvi Band
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-06 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A basic interface to the citywide API published by the District of Columbia
+email: zvi@skeevisarts.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+files: 
+- LICENSE
+- README
+- Rakefile
+- lib/dcgov
+- lib/dcgov/address.rb
+- lib/dcgov/easy_class_maker.rb
+- lib/dcgov/geocoder.rb
+- lib/dcgov/open311.rb
+- lib/dcgov/service_request.rb
+- lib/dcgov/service_request_field.rb
+- lib/dcgov/service_type.rb
+- lib/dcgov/util.rb
+- lib/dcgov.rb
+- spec/geocoder_spec.rb
+- spec/open_311_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://skeevisarts.com
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: A basic interface to the citywide API published by the District of Columbia
+test_files: []
+