Address verification for Ruby and Rails
š Supports international addresses
Add this line to your applicationās Gemfile:
gem "mainstreet"
MainStreet uses Geocoder for address verification, which has a number of 3rd party services you can use. If you adhere to GDPR, be sure to add the service to your subprocessor list.
With some services, bad street numbers, units, and postal codes may pass verification. For full verification, get an account with SmartyStreets. The free plan supports 250 lookups per month for US addresses, and plans for international addresses start at $7. To use it, set:
ENV["SMARTY_STREETS_AUTH_ID"] = "auth-id"
ENV["SMARTY_STREETS_AUTH_TOKEN"] = "auth-token"
Check an address with:
address = "1600 Pennsylvania Ave NW, Washington DC 20500"
verifier = MainStreet::AddressVerifier.new(address)
verifier.success?
If verification fails, get the failure message with:
verifier.failure_message
Get details about the result with:
verifier.result
Get the latitude and longitude with:
verifier.latitude
verifier.longitude
For Active Record models, use:
class User < ApplicationRecord
validates_address fields: [:street, :street2, :city, :state, :postal_code]
end
The order should be the same as if you were to write the address out.
For performance, the address is only verified if at least one of the fields changes. Set your own condition with:
class User < ApplicationRecord
validates_address if: -> { something_changed? }, ...
end
Geocode the address with:
class User < ApplicationRecord
validates_address geocode: true, ...
end
The latitude
and longitude
fields are used by default. Specify the fields with:
class User < ApplicationRecord
validates_address geocode: {latitude: :lat, longitude: :lon}, ...
end
Empty addresses are not verified. To require an address, add your own validation.
class User < ApplicationRecord
validates :street, presence: true
end
With SmartyStreets, you must pass the country for non-US addresses.
MainStreet::AddressVerifier.new(address, country: "France")
Hereās the list of supported countries. You can pass the name, ISO-3, ISO-2, or ISO-N code (like France
, FRA
, FR
, or 250
).
For Active Record, use:
class User < ApplicationRecord
validates_address country: "France", ...
end
Or use a proc to make it dynamic
class User < ApplicationRecord
validates_address country: -> { country }, ...
end
You can customize error messages with the i18n gem. In Rails, add to the appropriate config/locales
file:
en:
mainstreet:
errors:
messages:
unconfirmed: Address can't be confirmed
apt_unconfirmed: Apartment or suite can't be confirmed
apt_missing: Apartment or suite is missing
We recommend encrypting street information and postal code (at the very least) for user addresses. Lockbox is great for this. Check out this article for more details.
class User < ApplicationRecord
has_encrypted :street, :postal_code
end
View the changelog
Everyone is encouraged to help improve this project. Here are a few ways you can help:
- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features
To get started with development:
git clone https://github.com/ankane/mainstreet.git
cd mainstreet
bundle install
bundle exec rake test