alt 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e07bfd91aa9ad068c22ce47b3fbe15791e63b2ea99f2d43b4fcd2d8cb0b8851
-  data.tar.gz: 889d6574ec7935e0ef9a2fd087550c734373ace1b406501df2780015117db80e
+  metadata.gz: ff6375beb17a5e6f0ff9244e5b87cc4906f717644a34228fa22e58e58137070d
+  data.tar.gz: 206eee4de38abd0d516a341d72830c973f6ddac5c0e0978370d21550e6c38acc
 SHA512:
-  metadata.gz: 3fb473e309e1cf32f142e21389d81e10d093d764a02ce8f80d965e9b30a3175509b00f7031c16dcab8925eac398246dfbab643f3e66e0c23442eefd7b6c51763
-  data.tar.gz: 07a0aff38604788da60de4724f0864190d7c58bad7f4b8747bdbf94798a8ce412ac3f9de6cb1139d0d1334796ec2f0d09a0bcd2d44430e9d7a0e3872822a7e27
+  metadata.gz: 504da64a13fd24f9775f39533417c7875cb045f6c14e933a811a6e8dc8bbf5664a40b37901855bb7babc2766fdc8983f38b587de6c465a869fccd6f45d83b1ed
+  data.tar.gz: 07b2559f1ff20a650363c53980bb3588f581be639ab0e91f0d18903187df6c060c3c79e329fd78fc5f8430c15b17dcbb6f32984d1eae164c25e6bbdfa31df3bc

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [Unreleased]
+
+## [2.0.0] - 2026-09-10
+
+- [Breaking change] `Alt::Property#property_details` is gone, and `#facts` answers in its
+  place. Where the old method handed back Realtor's whole 73-key document, the new one
+  answers only the facts worth keeping, each named by what it is: `Bedrooms`, `Lot size`
+  (in acres), `Living area`, `Bathrooms`, `Year built`, `Stories`, `Garage spaces`,
+  `Fireplaces`, `Property type`, `Heating system`, `Heating fuel`, `Cooling`, `Roof`,
+  `Construction`, `Sewer`, `Foundation`, `Pool`, `Outdoor living`, `Fence` and
+  `Sprinklers`. A fact the listing does not state is left out rather than answered as a
+  zero or a `false`, since the response cannot tell "no pool" from "no mention of a pool".
+- [Feature] The MLS dialect a listing is written in is mapped onto a closed set of options.
+  One fact is spelled many ways — `Warm Air`, `Forced Air` and `ForcedAir` are one heating
+  system, `Asphalt Shingle`, `Composition` and `Architectural Shingles` are one roof — and
+  a comma-joined value carries two facts at once, so `Forced Air, Natural Gas` answers a
+  heating system and a heating fuel separately. Every option was derived from 329 real
+  enrichments, and everything the mapping does not name answers `Other`.
+- [Feature] `Coordinate` answers the point Realtor places the home at, as `[lat, lon]`. It
+  is the one entry not meant for storage: a host pins the place with it and drops it, since
+  a precise coordinate kept beside a street is personal data.
+- [Fix] An acre is 43,560 square feet, not 43,561. `Lot size` was previously computed by
+  whoever called this gem, using the second number.
+
 ## [1.0.1] - 2026-08-24
 
 - [Fix] Raise Error when autocomplete doesn't return a valid address.

data/README.md

@@ -1,8 +1,27 @@
 # Realtor API Ruby client
 
-Fetches property details from Realtor, reached through
+Fetches the facts Realtor states about a home, reached through
 [RapidAPI](https://rapidapi.com/apidojo/api/realty-in-us).
 
+- Source: https://github.com/claudiob/alt
+- API reference: https://rubydoc.info/gems/alt
+
+## How to install
+
+Install the gem system-wide:
+
+```sh
+gem install alt
+```
+
+Or add it to a Gemfile, pinned to the current major:
+
+```ruby
+gem 'alt', '~> 2.0'
+```
+
+`~> major.minor` means `bundle update` never crosses a breaking change.
+
 ## Authentication
 
 Subscribe to the Realtor API on RapidAPI and set your key as an environment variable:
@@ -16,11 +35,42 @@ The host (`realty-in-us.p.rapidapi.com`) is sent automatically as `X-RapidAPI-Ho
 ```ruby
 property = Alt::Property.new address: "4352 Desert Park Ave", unit: nil, city: "North Las Vegas", zipcode: "89085"
 
-property.property_details # => the parsed `/properties/v3/detail` response body
+property.facts
+# => { "Lot size" => 0.1837, "Living area" => 3000, "Bedrooms" => 5, "Bathrooms" => 2,
+#      "Year built" => 1999, "Stories" => 2, "Garage spaces" => 3, "Fireplaces" => 2,
+#      "Property type" => "Single family", "Heating system" => "Forced air",
+#      "Heating fuel" => "Natural gas", "Cooling" => "Central air",
+#      "Roof" => "Asphalt shingle", "Construction" => "Brick", "Sewer" => "Public",
+#      "Foundation" => "Slab", "Pool" => "Yes", "Outdoor living" => "Yes",
+#      "Fence" => "Yes", "Sprinklers" => "Yes", "Coordinate" => [36.2814, -115.1543] }
 ```
 
-Unlike HouseCanary, which returns separate `subject_address`, `public_records` and
-`assessment` objects, Realtor returns a single object, exposed here as `property_details`.
+Every key is named after the fact it states, so a host stores each under whatever it calls
+it. A fact the listing does not state is **left out** rather than answered as a zero or a
+`false`: the response cannot tell "no pool" from "no mention of a pool", and a value that
+says the second while meaning the first is worse than no value at all.
+
+`Coordinate` is the one entry not meant for storage. It answers `[lat, lon]` so that a host
+can place the home on a map; a precise coordinate kept beside a street address is personal
+data, so pin with it and drop it.
+
+Nothing else Realtor sends comes back. The response also carries the street, an `href`
+whose slug is the street address, the listing agent's name, email and phones, and a Street
+View URL embedding both the address and a live Maps key — an allow-list rather than a
+deny-list is what keeps all of it out.
+
+## How a fact is read
+
+Realtor answers two blocks worth reading: `description`, which states the home's own
+figures and its kind, and `details`, an array of `{ category, text[] }` where each `text`
+entry is a `"Label: value"` sentence written in whichever dialect the listing MLS uses.
+
+One fact is spelled many ways, and a comma-joined value carries two facts at once. So each
+choice is mapped onto a closed set of options — `Warm Air`, `Forced Air` and `ForcedAir`
+are all `Forced air`; `Forced Air, Natural Gas` answers a heating system *and* a heating
+fuel — and anything the mapping does not name answers `Other`. The options were derived
+from 329 real enrichments rather than from the API's documentation, which does not describe
+these fields.
 
 ## How a lookup works
 
@@ -30,13 +80,3 @@ Realtor has no address-to-detail endpoint, so a lookup takes two requests:
 2. `GET /properties/v3/detail?property_id=<id>` — returns the details
 
 `Alt::Error` is raised when either request fails, or when the address matches no property.
-
-## Status
-
-The two endpoint paths above are confirmed to exist. The following identifiers are **not yet
-verified against a live response** (the account's RapidAPI quota was exhausted at the time of
-writing) and should be checked against the RapidAPI playground before relying on this client:
-
-- the `input` query parameter name for `/locations/v2/auto-complete`
-- the `autocomplete` array and its `mpr_id` field in that response
-- the `property_id` query parameter name for `/properties/v3/detail`

data/lib/alt/property/climate.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Alt
+  class Property
+    # Reads how a home is heated and cooled, which one line states in two parts.
+    module Climate
+      # The line an MLS states heating on, e.g. 'Heating Features: Forced Air, Natural Gas'.
+      HEATING = /\AHeating( Features| System)?\s*:/i
+
+      # The line it states cooling on, e.g. 'Cooling: Central Air'.
+      COOLING = /\ACooling( Features)?\s*:/i
+
+    private
+
+      def climate
+        heating = detail HEATING
+        { 'Heating system' => heating_system_of(heating),
+          'Heating fuel' => heating_fuel_of(heating),
+          'Cooling' => cooling_of(detail(COOLING)), }.compact
+      end
+
+      def heating_system_of(heating)
+        return unless heating
+
+        case heating
+          when /heat ?pump/i then 'Heat pump'
+          when /(warm|forced|hot) air|forcedair/i then 'Forced air'
+          when /hot water|forced water|radiator|steam|boiler/i then 'Hot water'
+          when /baseboard/i then 'Baseboard'
+          when /central/i then 'Central'
+          else 'Other'
+        end
+      end
+
+      def heating_fuel_of(heating)
+        case heating
+          when /electric/i then 'Electric'
+          when /propane/i then 'Propane'
+          when /natural gas|\bgas\b/i then 'Natural gas'
+          when /\boil\b/i then 'Oil'
+        end
+      end
+
+      def cooling_of(cooling)
+        return unless cooling
+
+        case cooling
+          when /central|package/i then 'Central air'
+          when /heat ?pump/i then 'Heat pump'
+          when /wall|window|room|individual/i then 'Wall or window'
+          when /evaporative/i then 'Evaporative'
+          when /fan/i then 'Ceiling fan'
+          else 'Other'
+        end
+      end
+    end
+  end
+end

data/lib/alt/property/described.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Alt
+  class Property
+    # Reads Realtor's `description`, which states a home's own figures and its kind.
+    module Described
+      # The square feet in an acre, which is the unit a lot is worth storing in.
+      ACRE = 43_560.0
+
+    private
+
+      def described
+        { 'Lot size' => acres, 'Living area' => description[:sqft],
+          'Bedrooms' => description[:beds], 'Bathrooms' => description[:baths],
+          'Year built' => description[:year_built], 'Stories' => description[:stories],
+          'Garage spaces' => description[:garage],
+          'Property type' => property_type_of(description[:type]), }.compact
+      end
+
+      def acres
+        sqft = description[:lot_sqft]
+        sqft / ACRE if sqft
+      end
+
+      def description = home[:description] || {}
+
+      def property_type_of(type)
+        return unless type
+
+        case type
+          when 'single_family' then 'Single family'
+          when /townhome/ then 'Townhome'
+          when 'condo', 'condos', 'apartment' then 'Condo'
+          when 'land', 'farm' then 'Land'
+          else 'Other'
+        end
+      end
+    end
+  end
+end

data/lib/alt/property/detailed.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Alt
+  class Property
+    # Reads Realtor's `details`, whose lines are sentences labeled by what they state.
+    module Detailed
+    private
+
+      def detail(label)
+        line = detail_lines.grep(label).first
+        line.split(':', 2).last.strip if line
+      end
+
+      def detail_lines
+        Array(home[:details]).flat_map { |one| Array one[:text] }
+      end
+    end
+  end
+end

data/lib/alt/property/exterior.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Alt
+  class Property
+    # Reads what a home is roofed and clad with.
+    module Exterior
+      # The line an MLS states a roof on, e.g. 'Roof: Asphalt Shingle'.
+      ROOF = /\ARoof(ing)?\s*:/i
+
+      # The three headings it files the walls under, e.g. 'Construction Materials: Brick'.
+      CONSTRUCTION = /\A(Construction Materials|Building Exterior Type|Exterior)\s*:/i
+
+    private
+
+      def exterior
+        { 'Roof' => roof_of(detail(ROOF)),
+          'Construction' => construction_of(detail(CONSTRUCTION)), }.compact
+      end
+
+      def roof_of(roof)
+        return unless roof
+
+        case roof
+          when /tile/i then 'Tile'
+          when /slate|slag/i then 'Slate'
+          when /metal|corrugated/i then 'Metal'
+          when /wood|shake|cedar/i then 'Wood'
+          when /shingle|asphalt|composition|fiberglass/i then 'Asphalt shingle'
+          else 'Other'
+        end
+      end
+
+      def construction_of(construction)
+        return unless construction
+
+        case construction
+          when /brick/i then 'Brick'
+          when /vinyl/i then 'Vinyl'
+          when /wood|cedar|clapboard|shake|frame/i then 'Wood'
+          when /aluminum/i then 'Aluminum'
+          when /stucco|plaster|stone|concrete|block|cement|hardi/i then 'Masonry'
+          else 'Other'
+        end
+      end
+    end
+  end
+end

data/lib/alt/property/grounds.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Alt
+  class Property
+    # Reads what a home has outside its walls.
+    module Grounds
+      # A pool of the home's own, anchored so that a community one is not taken for one.
+      POOL = /\APool/i
+
+      # Somewhere to sit out, e.g. 'Patio And Porch Features: Covered, Deck'.
+      OUTDOOR = /\A(Patio|Deck|Porch)/i
+
+      # A fence, however the MLS spells it: 'Fencing', 'Fence YN', 'Fenced Yard'.
+      FENCE = /\AFenc/i
+
+      # An irrigation system, e.g. 'Sprinkler System'. A fire sprinkler is labeled otherwise.
+      SPRINKLERS = /\ASprinkler/i
+
+      # The four headings an MLS states where the waste goes under, e.g. 'Sewer: Public'.
+      SEWER = /\A(Sewer|Septic|City Sewer|Public Sewer)/i
+
+    private
+
+      def grounds
+        { 'Pool' => ('Yes' if detail(POOL)),
+          'Outdoor living' => ('Yes' if detail(OUTDOOR)),
+          'Fence' => ('Yes' if detail(FENCE)),
+          'Sprinklers' => ('Yes' if detail(SPRINKLERS)),
+          'Sewer' => sewer_of(detail(SEWER)), }.compact
+      end
+
+      def sewer_of(sewer)
+        return unless sewer
+
+        case sewer
+          when /septic/i then 'Septic'
+          when /private/i then 'Private'
+          when /public|city|municipal|connected/i then 'Public'
+          else 'Other'
+        end
+      end
+    end
+  end
+end

data/lib/alt/property/placed.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Alt
+  class Property
+    # Reads where Realtor says the home stands, which a host pins with rather than keeps.
+    module Placed
+    private
+
+      def placed
+        { 'Coordinate' => coordinate.values_at(:lat, :lon) }
+      end
+
+      def coordinate = home.dig(:location, :address, :coordinate) || {}
+    end
+  end
+end

data/lib/alt/property/structure.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Alt
+  class Property
+    # Reads what a home stands on and what is built into it.
+    module Structure
+      # The line an MLS states what the house stands on, e.g. 'Foundation Details: Slab'.
+      FOUNDATION = /\AFoundation/i
+
+      # A counted fireplace, since 'Fireplace features' describes them rather than counting.
+      FIREPLACES = /\A(Number of )?Fireplaces\b[^:]*:\s*\d/i
+
+    private
+
+      def structure
+        { 'Foundation' => foundation_of(detail(FOUNDATION)),
+          'Fireplaces' => detail(FIREPLACES)&.to_i, }.compact
+      end
+
+      def foundation_of(foundation)
+        return unless foundation
+
+        case foundation
+          when /slab/i then 'Slab'
+          when /crawl/i then 'Crawl space'
+          when /block/i then 'Block'
+          when /concrete|perimeter|poured/i then 'Concrete'
+          when /stone|brick/i then 'Stone'
+          else 'Other'
+        end
+      end
+    end
+  end
+end

data/lib/alt/property.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 # A wrapper for the Realtor API, reached through RapidAPI, to fetch property details.
 # @see https://rapidapi.com/apidojo/api/realty-in-us
 module Alt
   # Embeds the logic of a Realtor property.
   class Property
+    include Climate, Described, Detailed, Exterior, Grounds, Placed, Structure
+
     # The RapidAPI host serving the Realtor data.
     HOST = 'realty-in-us.p.rapidapi.com'
 
@@ -15,13 +19,15 @@ module Alt
       @data = data
     end
 
-    # @return [Hash] Details about the property
-    def property_details = details
+    # @return [Hash] every fact Realtor states about the property, named by what it is.
+    def facts = [climate, described, exterior, grounds, placed, structure].inject :merge
 
   private
 
-    def details
-      @details ||= fetch
+    def home = response.dig(:data, :home) || {}
+
+    def response
+      @response ||= fetch
     end
 
     # Realtor exposes no address-to-detail endpoint, so the address is resolved to an id first.

data/lib/alt/version.rb

@@ -1,3 +1,3 @@
 module Alt
-  VERSION = '1.0.1'
+  VERSION = '2.0.0'
 end

data/lib/alt.rb

@@ -6,4 +6,11 @@ require 'net/http'
 require 'uri'
 
 require 'alt/error'
+require 'alt/property/climate'
+require 'alt/property/described'
+require 'alt/property/detailed'
+require 'alt/property/exterior'
+require 'alt/property/grounds'
+require 'alt/property/placed'
+require 'alt/property/structure'
 require 'alt/property'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alt
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -36,6 +36,13 @@ files:
 - lib/alt.rb
 - lib/alt/error.rb
 - lib/alt/property.rb
+- lib/alt/property/climate.rb
+- lib/alt/property/described.rb
+- lib/alt/property/detailed.rb
+- lib/alt/property/exterior.rb
+- lib/alt/property/grounds.rb
+- lib/alt/property/placed.rb
+- lib/alt/property/structure.rb
 - lib/alt/version.rb
 homepage: https://github.com/claudiob/alt
 licenses:
@@ -43,7 +50,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/claudiob/alt
   source_code_uri: https://github.com/claudiob/alt
-  changelog_uri: https://github.com/claudiob/alt
+  changelog_uri: https://github.com/claudiob/alt/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/alt
 rdoc_options: []
 require_paths:
 - lib