miami_dade_geo 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 210a82e58eb4f992fa654034a01607526b98802a
-  data.tar.gz: 10d42cedd1ca2c88dd62fe9d6d5ba8842a487519
+  metadata.gz: a277a7b75e101dc40eb9f482a18e1707ddcbe0a9
+  data.tar.gz: bcc7ed55b71bf645472550ef5da262df6290a0df
 SHA512:
-  metadata.gz: 389e3de1c57bab9936f87708e8c40b96cce18d71620d492f01b1df1b87907a96645f5e32550e528a6e6f9984dcbcb2a54db2c630ced36cdb50d36047696ad1c7
-  data.tar.gz: 829b850d956e8a7b3dac2ca62bf71f63470a3b48842a4a2bb0cfd4a39147d062bed4e5acc1f1303e51f3c133df9e8164ac5849d3deb58492cc0fe7bff3697cd8
+  metadata.gz: 7d9d4718cac3630a5ac9f54caa40e4a977fc07b64924f6a15810eef7722846f079ad06e85edca2dfa36928e1f0dbb739d10fa6753745e7a983e960f039aeace7
+  data.tar.gz: d07dfb923f7f5122dbc3260fd1c3e04969590762c08f029de60d989b7200999243f8cdc0dc165c825f165284e402d743a887802271a4c195664579cba2cce1b4

data/.travis.yml

@@ -3,3 +3,5 @@ language: ruby
 rvm:
   - 2.3.1
 before_install: gem install bundler -v 1.12.3
+notifications:
+  email: false

data/README.md

@@ -5,13 +5,13 @@ This library wraps some of the Miami-Dade County geospatial services, including:
 * Address to NAD 83 State Plane X and Y coordinate
 * NAD 83 State Plane X and Y coordinate to latitude and longitude
 
-## Installation
+# Installation #
 
 Add this line to your application's Gemfile:
 
-```ruby
+~~~ruby
 gem 'miami_dade_geo'
-```
+~~~
 
 And then execute:
 
@@ -23,7 +23,47 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Coordinate to Address
+
+~~~ruby
+coordinate = MiamiDadeGeo::Coordinate.new(long: -80.199245566240819,
+                                          lat: 25.7999410593211)
+addr = coordinate.address
+addr.address #=> "2390 NW 2ND AVE"
+addr.zip #=> 33127
+~~~
+
+### Address to Coordinate
+
+~~~ruby
+addr = MiamiDadeGeo::Address.new '2390 NW 2nd Ave'
+addr.zip #=> 33127
+addr.lat #=> 25.7999410593211
+addr.long #=> -80.199245566240819
+addr.municipality.name #=> "MIAMI"
+~~~
+
+### Coordinate to Municipality
+
+~~~ruby
+muni = MiamiDadeGeo::Municipality.new_with_latlong(
+  long: -80.199245566240819,
+  lat: 25.7999410593211)
+
+muni.name #=> "MIAMI"
+~~~
+
+## Links
+
+* <https://rubygems.org/gems/miami_dade_geo>
+
+* <https://github.com/jdiago/miami_dade_geo_api>
+
+* <https://github.com/bkerley/what_municipality>
+
+* <https://radiant-taiga-73968.herokuapp.com/address-meta?address=2390%20NW%202nd%20Ave>
+
+* <https://what-mdc-muni.herokuapp.com>
 
 ## Development
 

data/Rakefile

@@ -1,6 +1,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
+YARD::Rake::YardocTask.new(:doc)
 
 task :default => :spec

data/lib/miami_dade_geo.rb

@@ -2,6 +2,6 @@
   require "miami_dade_geo/#{f}"
 end
 
+# `MiamiDadeGeo` provides geospatial data access for Miami-Dade County.
 module MiamiDadeGeo
-  # Your code goes here...
 end

data/lib/miami_dade_geo/addr_xy_client.rb

@@ -2,11 +2,31 @@ require 'singleton'
 require 'savon'
 
 module MiamiDadeGeo
+  # Singleton SOAP client for converting an address to NAD 83 x-y coordinates.
+  # Makes one SOAP request for WSDL on first instantiation.
+  #
+  # @api private
   class AddrXyClient
     include Singleton
 
+    # URL to AddrXy service WSDL
     WSDL_URL = "http://gisws.miamidade.gov/gisaddress/addrxy.asmx?wsdl"
-    
+
+    def xy_for_address(address)
+      body = savon.
+             call(:xy_address, message: { myAddress: address}).
+             body
+
+      if body[:xy_address_response][:xy_address_result][:count] == '0'
+        raise MiamiDadeGeo::InvalidAddressError
+      end
+
+      body[:xy_address_response][:xy_address_result][:xy][:arr_xy]
+    end
+
+    # Returns a Savon SOAP client instance
+    #
+    # @return [Savon::Client]
     def savon
       @savon ||= Savon.client(wsdl: WSDL_URL)
     end

data/lib/miami_dade_geo/address.rb

@@ -1,83 +1,101 @@
 require 'miami_dade_geo/addr_xy_client'
-require 'miami_dade_geo/latlong_client'
+require 'miami_dade_geo/coordinate'
 require 'miami_dade_geo/municipality'
 require 'miami_dade_geo/errors/invalid_address_error'
 
 module MiamiDadeGeo
+  # A street address in Miami-Dade County.
+  # Lazily makes up to two SOAP requests:
+  # one to get the X and Y coordinates, and one to convert them to standard
+  # latitude and longitude.
+  #
+  # Can raise an [InvalidAddressError] when lazily making the initial SOAP
+  # request if the given address does not exist.
+  #
+  # @raise [InvalidAddressError]
   class Address
+    attr_reader :feature
+
+    # @!attribute [r] address
+    # @return [String] the street address
     attr_reader :address
 
-    def initialize(address)
-      @address = address
+    # @!attribute [rw] zip
+    # @return [String] the ZIP code
+    attr_accessor :zip
+
+    # Construct the address object
+    # @param address [String] the street address
+    def self.new_from_address(address)
+      xy = AddrXyClient.instance.xy_for_address(address)
+
+      Coordinate.new(xy).address
+    end
+
+    def self.new_from_feature(feature)
+      new feature
+    end
+
+    # @return [Coordinate] a coordinate object representing where this address
+    # even is
+    def coordinate
+      @coordinate ||= Coordinate.new xy_addr
     end
 
+    # @return [Float] the x-coordinate of the address
     def x
-      @x ||= xy_addr[:x].to_f
+      coordinate.x
     end
 
+    # @return [Float] the y-coordinate of the address
     def y
-      @y ||= xy_addr[:y].to_f
+      coordinate.y
     end
 
+    # @return [Integer] the ZIP code of the address
     def zip
       @zip ||= xy_addr[:zip_code].to_i
     end
 
+    # @return [Integer] the municipality code of the address
     def munic_code
       @munic_code ||= xy_addr[:munic_code].to_i
     end
 
+    # @return [Float] the latitude of the address
     def lat
-      @lat ||= latlong[:lat]
+      coordinate.lat
     end
 
+    # @return [Float] the longitude of the address
     def long
-      @long ||= latlong[:long]
+      coordinate.long
     end
 
+    # Constructs and returns a {Municipality} object. Makes one SOAP request.
+    # @return [Municipality]
     def municipality
       @municipality ||= Municipality.new_with_code(munic_code)
     end
 
+    def address
+      @address ||= [feature[:hse_num], feature[:sname]].join ' '
+    end
+
     private
 
-    def latlong
-      return @latlong if defined? @latlong
-      body = latlong_client.
-             call(:get_lat_long_dec_from_xy,
-                  message: { 'X' => x.to_s, 'Y' => y.to_s} ).
-             body
-
-      resp = body[:get_lat_long_dec_from_xy_response]
-      result = resp[:get_lat_long_dec_from_xy_result]
-      double = result[:double]
-
-      @latlong = {
-        long: double[0].to_f,
-        lat: double[1].to_f
-      }
+    def initialize(feature)
+      @feature = feature
     end
 
     def xy_addr
       return @xy_addr if defined? @xy_addr
 
-      body = addr_xy_client.
-             call(:xy_address, message: { myAddress: address}).
-             body
-
-      if body[:xy_address_response][:xy_address_result][:count] == '0'
-        raise MiamiDadeGeo::InvalidAddressError
-      end
-
-      @xy_addr = body[:xy_address_response][:xy_address_result][:xy][:arr_xy]
+      @xy_addr = addr_xy_client.xy_for_address(address)
     end
 
     def addr_xy_client
-      AddrXyClient.instance.savon
-    end
-
-    def latlong_client
-      LatlongClient.instance.savon
+      AddrXyClient.instance
     end
   end
 end

data/lib/miami_dade_geo/coordinate.rb

@@ -0,0 +1,101 @@
+require 'miami_dade_geo/latlong_client'
+require 'miami_dade_geo/get_closest_feature_client'
+
+module MiamiDadeGeo
+  class Coordinate
+    def initialize(opts)
+      if opts[:x] && opts[:y]
+        initialize_from_xy opts
+      elsif
+        opts[:lat] && opts[:long]
+        initialize_from_latlong opts
+      else
+        fail ArgumentError "Can't initialize without x & y or lat & long"
+      end
+    end
+
+    def initialize_from_xy(opts)
+      @x = opts[:x].to_f
+      @y = opts[:y].to_f
+    end
+
+    def initialize_from_latlong(opts)
+      @lat = opts[:lat].to_f
+      @long = opts[:long].to_f
+    end
+
+    def x
+      return @x if @x
+      load_xy_from_latlong
+      @x
+    end
+
+    def y
+      return @y if @y
+      load_xy_from_latlong
+      @y
+    end
+
+    def lat
+      return @lat if @lat
+      load_latlong_from_xy
+      @lat
+    end
+
+    def long
+      return @long if @long
+      load_latlong_from_xy
+      @long
+    end
+
+    def xy
+      { x: x, y: y }
+    end
+
+    def latlong
+      {  lat: lat, long: long }
+    end
+
+    def address
+      return @address if defined? @address
+      feature = get_closest_feature_client.find_feature(xy, 'GeoAddress')
+
+      @address = Address.new_from_feature feature
+    end
+
+    private
+    def load_xy_from_latlong
+      body = latlong_client.
+             call(:get_x_yfrom_lat_long_dec,
+                  message: { 'LNG' => long.to_s, 'LAT' => lat.to_s}).
+             body
+
+      resp = body[:get_x_yfrom_lat_long_dec_response]
+      result = resp[:get_x_yfrom_lat_long_dec_result]
+
+      @x = result[:double][0].to_f
+      @y = result[:double][1].to_f
+    end
+
+    def load_latlong_from_xy
+      body = latlong_client.
+             call(:get_lat_long_dec_from_xy,
+                  message: { 'X' => x.to_s, 'Y' => y.to_s} ).
+             body
+
+      resp = body[:get_lat_long_dec_from_xy_response]
+      result = resp[:get_lat_long_dec_from_xy_result]
+
+      @lat = result[:double][1].to_f
+      @long = result[:double][0].to_f
+    end
+
+    def get_closest_feature_client
+      GetClosestFeatureClient.instance
+    end
+
+    def latlong_client
+      LatlongClient.instance.savon
+    end
+  end
+end

data/lib/miami_dade_geo/errors/base.rb

@@ -1,4 +1,5 @@
 module MiamiDadeGeo
+  # Parent class for all errors this gem will raise.
   class Error < StandardError
   end
 end

data/lib/miami_dade_geo/errors/invalid_address_error.rb

@@ -1,6 +1,7 @@
 require 'miami_dade_geo/errors/base'
 
 module MiamiDadeGeo
+  # Error raised when an address cannot be found.
   class InvalidAddressError < Error
   end
 end

data/lib/miami_dade_geo/geo_attribute_client.rb

@@ -2,11 +2,23 @@ require 'singleton'
 require 'savon'
 
 module MiamiDadeGeo
+  # Singleton SOAP client for searching geographic attributes. Used to search
+  # for municipalities by name or `munic_code`. Makes one SOAP request for WSDL
+  # on first instantiation.
+  #
+  # @api private
   class GeoAttributeClient
     include Singleton
 
+    # URL to GeoAttribute service WSDL
     WSDL_URL = "http://gisws.miamidade.gov/gisdata/GeoAttribute.asmx?wsdl"
 
+    # Performs a search for geo-attributes.
+    #
+    # @param [String] table the table to search
+    # @param [String] field_name the field/column to search in the given table
+    # @param [String] value string value to search in the given field and table
+    # @return [Hash] search results
     def all_fields(table, field_name, value)
       body = savon.
              call(:get_all_fields_records_given_a_field_name_and_value,
@@ -29,7 +41,10 @@ module MiamiDadeGeo
                fail "Unexpected polys #{polys.class.name}, wanted Array or Hash"
              end
     end
-    
+
+    # Returns a Savon SOAP client instance
+    #
+    # @return [Savon::Client]
     def savon
       @savon ||= Savon.client(wsdl: WSDL_URL)
     end

data/lib/miami_dade_geo/get_closest_feature_client.rb

@@ -2,11 +2,55 @@ require 'singleton'
 require 'savon'
 
 module MiamiDadeGeo
+  # Singleton SOAP client for finding features close to a given point.
+  # Makes one SOAP request for WSDL on first instantiation.
+  #
+  # @api private
   class GetClosestFeatureClient
     include Singleton
 
-    WSDL_URL = "http://gisws.miamidade.gov/gisxyservices/GetClosestFeature.asmx?wsdl"
+    # URL to GetClosestFeature service WSDL
+    WSDL_URL =
+      "http://gisws.miamidade.gov/gisxyservices/GetClosestFeature.asmx?wsdl"
 
+    FIND_RADIUSES = [0, 10, 100, 1000, 5280, (20 * 5280)]
+
+    def find_feature(xy_hash, feature_class)
+      FIND_RADIUSES.each do |radius|
+        result = get_closest_feature(feature_class,
+                                     xy_hash[:x].to_s,
+                                     xy_hash[:y].to_s,
+                                     radius.to_s)
+
+        return result unless result.nil?
+      end
+
+      nil
+    end
+
+    def get_closest_feature(feature_class, x, y, buffer)
+      body = savon.
+             call(:get_closest_feature_from_xy_all_atrbts,
+                  message: {
+                    'X' => x,
+                    'Y' => y,
+                    'Buffer' => buffer,
+                    'NameOfFeatureClass' => feature_class
+                  }).
+             body
+
+      begin
+        resp = body[:get_closest_feature_from_xy_all_atrbts_response]
+        rslt = resp[:get_closest_feature_from_xy_all_atrbts_result]
+        poly = rslt[:diffgram][:document_element][:results]
+      rescue
+        nil
+      end
+    end
+
+    # Returns a Savon SOAP client instance
+    #
+    # @return [Savon::Client]
     def savon
       @savon ||= Savon.client(wsdl: WSDL_URL)
     end

data/lib/miami_dade_geo/latlong_client.rb

@@ -2,12 +2,21 @@ require 'singleton'
 require 'savon'
 
 module MiamiDadeGeo
+  # Singleton SOAP client for converting NAD 83 x-y coordinates to latitude and
+  # longitude, and back again. Makes one SOAP request for WSDL on first
+  # instantiation.
+  #
+  # @api private
   class LatlongClient
     include Singleton
 
+    # URL to XyLatLongConversions SOAP service WSDL
     WSDL_URL =
       "http://gisws.miamidade.gov/gisxyservices/XYLatLongConversions.asmx?wsdl"
-    
+
+    # Returns a Savon SOAP client instance
+    #
+    # @return [Savon::Client]
     def savon
       @savon ||= Savon.client(wsdl: WSDL_URL)
     end

data/lib/miami_dade_geo/municipality.rb

@@ -3,9 +3,30 @@ require 'miami_dade_geo/get_closest_feature_client'
 require 'miami_dade_geo/latlong_client'
 
 module MiamiDadeGeo
+  # Represents one of the municipalities in Miami-Dade County, and
+  # unincorporated Miami-Dade County as well.
+  #
+  # Makes one or two SOAP requests on construction.
+  #
+  # Doesn't have a `new` method for construction, since there are a few
+  # different ways to construct it.
   class Municipality
-    attr_reader :name, :munic_code
+    # @!attribute [r] name
+    # @return [String] the name of the municipality, or
+    #     unincorporated MDC.
+    attr_reader :name
 
+    # @!attribute [r] munic_code
+    # @return [Integer] the numeric code of the municipality
+    attr_reader :munic_code
+
+    # Constructs a {Municipality} object for a given municipality name. The
+    # SOAP method called is case-sensitive, and we believe all municipalities
+    # to be ALL-CAPS, so this constructor capitalizes the name before searching.
+    #
+    # Useful to get the `munic_code` for a given municipality name.
+    #
+    # @param [String] name case-insensitive name of the municipality
     def self.new_with_name(name)
       canonicalized_name = name.upcase
 
@@ -17,6 +38,13 @@ module MiamiDadeGeo
       new poly
     end
 
+    # Constructs a {Municipality} object for a given `munic_code`. The SOAP
+    # method called zero-pads single-digit municipality codes, so this
+    # constructor converts the code to an `Integer` and formats it.
+    #
+    # Used by the {Address#municipality} method.
+    #
+    # @param [Integer] munic_code numeric code for the municipality
     def self.new_with_code(munic_code)
       canonicalized_munic_code = "%02d" % [munic_code.to_i]
 
@@ -28,23 +56,29 @@ module MiamiDadeGeo
       new poly
     end
 
+    # Constructs a {Municipality} object for a given x-y coordinate in
+    # the NAD 83 Florida state coordinate system. Calls one SOAP method.
+    #
+    # @param [Hash] xy_hash NAD 83 coordinates of a location inside a
+    #   municipality
+    # @option xy_hash [Float] :x x-coordinate
+    # @option xy_hash [Float] :y y-coordinate
     def self.new_with_xy(xy_hash)
-      body = GetClosestFeatureClient.instance.savon.
-             call(:get_closest_feature_from_xy_all_atrbts,
-                  message: {
-                    'X' => xy_hash[:x],
-                    'Y' => xy_hash[:y],
-                    'Buffer' => 0,
-                    'NameOfFeatureClass' => 'municipality_poly'
-                  }).
-             body
-      resp = body[:get_closest_feature_from_xy_all_atrbts_response]
-      rslt = resp[:get_closest_feature_from_xy_all_atrbts_result]
-      poly = rslt[:diffgram][:document_element][:results]
-
-      new poly
+      new GetClosestFeatureClient.instance.
+           get_closest_feature('municipality_poly',
+                               xy_hash[:x],
+                               xy_hash[:y],
+                               0)
     end
 
+    # Constructs a {Municipality} object for a given latitude and longitude.
+    # Makes two SOAP requests: one to convert from lat-long to x-y in NAD 83,
+    # and one to load the municipality for the NAD 83 coordinate.
+    #
+    # @param [Hash] latlong_hash latitude and longitude hash of a locatio inside
+    #   a municipality
+    # @option latlong_hash [Float] :lat latitude coordinate
+    # @option latlong_hash [Float] :long longitude coordinate
     def self.new_with_latlong(latlong_hash)
       body = LatlongClient.instance.savon.
              call(:get_x_yfrom_lat_long_dec,

data/lib/miami_dade_geo/version.rb

@@ -1,3 +1,4 @@
 module MiamiDadeGeo
-  VERSION = "0.2.0"
+  # Current gem version
+  VERSION = "0.3.0"
 end

data/miami_dade_geo.gemspec

@@ -25,6 +25,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "vcr", "~> 3.0"
   spec.add_development_dependency 'webmock', "~> 2.1"
   spec.add_development_dependency 'guard-rspec', "~> 4.7"
+  spec.add_development_dependency 'yard', "~> 0.8"
+  spec.add_development_dependency 'kramdown', "~> 1.11"
 
   spec.add_dependency 'savon', '~> 2.11.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: miami_dade_geo
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Bryce Kerley
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-04 00:00:00.000000000 Z
+date: 2016-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -95,6 +95,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
 - !ruby/object:Gem::Dependency
   name: savon
   requirement: !ruby/object:Gem::Requirement
@@ -131,6 +159,7 @@ files:
 - lib/miami_dade_geo.rb
 - lib/miami_dade_geo/addr_xy_client.rb
 - lib/miami_dade_geo/address.rb
+- lib/miami_dade_geo/coordinate.rb
 - lib/miami_dade_geo/errors/base.rb
 - lib/miami_dade_geo/errors/invalid_address_error.rb
 - lib/miami_dade_geo/geo_attribute_client.rb