A Ruby library to connects to MLS servers conforming to the RESO Web API standard.

Gem Version Build Status Test Coverage Maintainability Documentation


Add this line to your application's Gemfile:

gem 'reso_web_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install reso_web_api



Instantiating an API client requires two things: an endpoint (i.e. service URL) and an authentication strategy. You may either instantiate the auth strategy directly and pass it to the client constructor (in the :auth parameter), or you may choose to pass a nested hash with options for configuring the strategy instead, as below:

require 'reso_web_api'

client =
  endpoint: '',
  auth: {
    strategy:      ResoWebApi::Authentication::TokenAuth,
    endpoint:      '',
    client_id:     'deadbeef',
    client_secret: 'T0pS3cr3t',
    scope:         'odata'

Note that if you choose this option, you may specify the strategy implementation by passing its class as the :strategy option. If you omit the :strategy parameter, it will default to ResoWebApi::Authentication::TokenAuth.

Accessing Data

Standard Resources

Since most RESO Web API servers will likely adhere to the RESO Data Dictionary, we've created some shortcuts for the standard resources

# Iterate over all properties -- WARNING! Might take a long time do |property|
  puts "#{property['ListPrice']} #{property['StandardStatus']}"

The following methods are provided:

  • Property: use #properties
  • Member: use #members
  • Office: use #office
  • Media: use #media

Other Resources

Other resources may be access using the #resources method on the client, which may be accessed as a hash like this:

client.resources['OpenHouse'].first # Access the 'OpenHouse' collectionh


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at


The gem is available as open source under the terms of the MIT License.