alt 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c95bf250ed92251331f64ee9538ab2389d02a846d9e18252ae74222f7c69dee
-  data.tar.gz: 865437becd4108c1f0cd93d31ab804da714eb4677477c6faf023612a3a5200f1
+  metadata.gz: 563d2fc47056480cff9fa2d26ea4b281d217ac8d267815c82b70097d50b600b1
+  data.tar.gz: e329a3b293b1a192b127e4451f53b65b741917b1d421ab45813a268d81db68bd
 SHA512:
-  metadata.gz: 45780d134aa7a48290183ad1b5b4ed5b433364256cf466666e50b333274fee54ec18002a49d3c4cd47fc3bc9daaab12ab226069a081d1575f4461e9c9f286e01
-  data.tar.gz: a0711bdc3d3da14fe9d3704ec6b5c7e51c51435e84c10f8055531cb7e9f2043f4764a7de310363b6379d727c880fad24eadf6c6bdf5cb8cc5f262c033c55a559
+  metadata.gz: 8611ddf2d4bdf9f70888aebf8279d82ebeb10ed254676aa63735968340230ce0f7b1387344233badf57f6c9bf256628558cc9a053ddd9063104c761ca6600f01
+  data.tar.gz: f801ba6e3f41630923742bb836822c327a24e2ddd7c2af39cec0c5b2bcd555ad71e4bec77edbcec50bca1c579819edb96214156d85b3f0782d58ded3cd7ee862

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.0.0] - 2026-08-05
+
+- Implement `Alt::Property#property_details`, which was previously a `# TODO` returning `nil`.
+  A lookup now issues two requests against RapidAPI's `realty-in-us` host: an
+  `/locations/v2/auto-complete` call to resolve the address to a property id, then a
+  `/properties/v3/detail` call for the details.
+
 ## [0.0.2] - 2026-07-28
 
 - Initial release

data/README.md

@@ -1,20 +1,42 @@
-# HouseCanary API Ruby client
+# Realtor API Ruby client
+
+Fetches property details from Realtor, reached through
+[RapidAPI](https://rapidapi.com/apidojo/api/realty-in-us).
 
 ## Authentication
 
-Generate an API key/secret in HouseCanary and set as environment variables:
+Subscribe to the Realtor API on RapidAPI and set your key as an environment variable:
+
+- `ENV['RAPIDAPI_KEY']`
 
-- `ENV['HOUSECANARY_API_KEY']`
-- `ENV['HOUSECANARY_API_SECRET']`
+The host (`realty-in-us.p.rapidapi.com`) is sent automatically as `X-RapidAPI-Host`.
 
 ## Available methods
 
 ```ruby
 property = Alt::Property.new address: "4352 Desert Park Ave", unit: nil, city: "North Las Vegas", zipcode: "89085"
 
-property.subject_address # => {msa: "29820", city: "North Las Vegas", fips: "32003", slug: "4352-Desert-Park-Ave-North-Las-Vegas-NV-89085", unit: "", state: "NV", address: "4352 Desert Park Ave", zipcode: "89085", block_id: "320030036621009", latitude: 36.31164, longitude: -115.20045, address_id: 8412516, address_full: "4352 Desert Park Ave North Las Vegas NV 89085", geo_precision: "rooftop", zipcode_plus4: "2321"}
+property.property_details # => the parsed `/properties/v3/detail` response body
+```
+
+Unlike HouseCanary, which returns separate `subject_address`, `public_records` and
+`assessment` objects, Realtor returns a single object, exposed here as `property_details`.
+
+## How a lookup works
+
+Realtor has no address-to-detail endpoint, so a lookup takes two requests:
+
+1. `GET /locations/v2/auto-complete?input=<address>` — resolves the address to a property id
+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
 
-property.public_records # => {pool: nil, attic: nil, sewer: nil, water: nil, zoning: {code: nil, description: nil}, cooling: nil, heating: ["Forced Air Unit"], parking: {total: 2, garage: nil, description: "Built-in"}, stories: 2, basement: {has: nil, total_area: nil, finished_pct: nil}, bedrooms: 4, lot_size: 4792, bathrooms: {full: nil, total: nil, partial: nil, total_provided: 3.0, total_projected: 3}, buildings: nil, fireplace: true, parcel_id: "12407312060", roof_type: nil, year_built: 2007, living_area: 2778, rooms_total: 9, subdivision: nil, units_total: nil, neighborhood: nil, sewer_public: nil, solar_panels: nil, property_type: "SFR", roof_material: "Tile", pool_community: nil, building_quality: nil, fireplaces_total: 1, legal_description: "DIST:NLV CITY/MUNI/TWP:NORTH LAS VEGAS SEC/TWN/RNG/MER:SEC 07 TWN 19S RNG 61E GRAND TETON VALLEY N W 80 PUD-45 #2 PLAT BOOK 123 PAGE 68 LOT 129 MAP REF:PB B0123 P0068", construction_types: ["Frame"], architectural_style: nil, building_condition_code: "Average", living_area_above_grade: nil, living_area_below_grade: nil, walls_exterior_material: "Stucco", property_type_description: "Single Family Residential"}
+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:
 
-property.assessment # => {apn: "124-07-312-060", tax_year: 2026, amount_annual: 2772.91, year_assessed: 2026, value_assessed: 150470, value_assessed_land: 35350, value_assessed_improvement: 115120}
-```
+- 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/error.rb

@@ -1,4 +1,4 @@
 module Alt
-  # An error to raise when HouseCanary API doesn't respond as expected.
+  # An error to raise when the Realtor API doesn't respond as expected.
   Error = Class.new(StandardError)
 end

data/lib/alt/property.rb

@@ -1,9 +1,12 @@
-# A wrapper for the HouseCanary API to fetch public records about a property.
-# @see https://api-docs.housecanary.com/#tag/Property-Level/
+# 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 HouseCanary property.
+  # Embeds the logic of a Realtor property.
   class Property
-    # @data [Hash] data the attributes of each provider
+    # The RapidAPI host serving the Realtor data.
+    HOST = 'realty-in-us.p.rapidapi.com'
+
+    # @data [Hash] data the attributes of each property
     # @option data [String] address Building number, street name, and optionally unit number
     # @option data [String] unit Unit number for the property
     # @option data [String] city City in which the property is located
@@ -12,8 +15,8 @@ module Alt
       @data = data
     end
 
-    # @return [Hash] Address information
-    def property_details = details[:property_details]
+    # @return [Hash] Details about the property
+    def property_details = details
 
   private
 
@@ -21,8 +24,33 @@ module Alt
       @details ||= fetch
     end
 
-    def fetch
-      # TODO
+    # Realtor exposes no address-to-detail endpoint, so the address is resolved to an id first.
+    def fetch = get '/properties/v3/detail', property_id: property_id
+
+    def property_id
+      suggestions = get('/locations/v2/auto-complete', input: input)[:autocomplete]
+      raise Error if suggestions.nil? || suggestions.empty?
+
+      suggestions.first[:mpr_id]
+    end
+
+    def input
+      [@data[:address], @data[:unit], @data[:city], @data[:zipcode]]
+        .reject { |part| part.to_s.empty? }.join ' '
+    end
+
+    def get(path, params)
+      uri = URI "https://#{HOST}#{path}"
+      uri.query = URI.encode_www_form params
+
+      request = Net::HTTP::Get.new uri
+      request['X-RapidAPI-Key'] = ENV['RAPIDAPI_KEY']
+      request['X-RapidAPI-Host'] = HOST
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(request)
+      end
+      raise Error unless response.is_a?(Net::HTTPSuccess)
+      JSON(response.body).with_indifferent_access
     end
   end
 end

data/lib/alt/version.rb

@@ -1,3 +1,3 @@
 module Alt
-  VERSION = '0.0.2'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alt
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -58,7 +58,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A Ruby client for the Realtor API.
 test_files: []