{"id":15632918,"url":"https://github.com/ankane/mainstreet","last_synced_at":"2025-11-17T14:16:37.924Z","repository":{"id":28720790,"uuid":"32241826","full_name":"ankane/mainstreet","owner":"ankane","description":" Address verification for Ruby and Rails","archived":false,"fork":false,"pushed_at":"2025-04-26T05:22:36.000Z","size":42,"stargazers_count":195,"open_issues_count":0,"forks_count":14,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-10-16T18:30:43.299Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ankane.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-03-15T02:34:53.000Z","updated_at":"2025-10-06T20:57:08.000Z","dependencies_parsed_at":"2024-06-10T05:29:41.343Z","dependency_job_id":"1de35124-a8ec-4dc4-90f8-79eb5764d9da","html_url":"https://github.com/ankane/mainstreet","commit_stats":{"total_commits":53,"total_committers":5,"mean_commits":10.6,"dds":0.5094339622641509,"last_synced_commit":"063741ab6408805782f0a48d9e98e20e1a9c178a"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/ankane/mainstreet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fmainstreet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fmainstreet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fmainstreet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fmainstreet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ankane","download_url":"https://codeload.github.com/ankane/mainstreet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankane%2Fmainstreet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284894653,"owners_count":27080744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-17T02:00:06.431Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T10:45:51.080Z","updated_at":"2025-11-17T14:16:37.900Z","avatar_url":"https://github.com/ankane.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# MainStreet\n\nAddress verification for Ruby and Rails\n\n:earth_americas: Supports international addresses\n\n[![Build Status](https://github.com/ankane/mainstreet/actions/workflows/build.yml/badge.svg)](https://github.com/ankane/mainstreet/actions)\n\n## Installation\n\nAdd this line to your application’s Gemfile:\n\n```ruby\ngem \"mainstreet\"\n```\n\n## How It Works\n\nMainStreet uses [Geocoder](https://github.com/alexreisner/geocoder) for address verification, which has a number of [3rd party services](https://github.com/alexreisner/geocoder/blob/master/README_API_GUIDE.md#global-street-address-lookups) you can use. If you adhere to GDPR, be sure to add the service to your subprocessor list.\n\nWith some services, bad street numbers, units, and postal codes may pass verification. For full verification, get an account with [SmartyStreets](https://smartystreets.com). The free plan supports 250 lookups per month for US addresses, and plans for international addresses start at $7. To use it, set:\n\n```ruby\nENV[\"SMARTY_STREETS_AUTH_ID\"] = \"auth-id\"\nENV[\"SMARTY_STREETS_AUTH_TOKEN\"] = \"auth-token\"\n```\n\n## How to Use\n\nCheck an address with:\n\n```ruby\naddress = \"1600 Pennsylvania Ave NW, Washington DC 20500\"\nverifier = MainStreet::AddressVerifier.new(address)\nverifier.success?\n```\n\nIf verification fails, get the failure message with:\n\n```ruby\nverifier.failure_message\n```\n\nGet details about the result with:\n\n```ruby\nverifier.result\n```\n\nGet the latitude and longitude with:\n\n```ruby\nverifier.latitude\nverifier.longitude\n```\n\n## Active Record\n\nFor Active Record models, use:\n\n```ruby\nclass User \u003c ApplicationRecord\n  validates_address fields: [:street, :street2, :city, :state, :postal_code]\nend\n```\n\nThe order should be the same as if you were to write the address out.\n\nFor performance, the address is only verified if at least one of the fields changes. Set your own condition with:\n\n```ruby\nclass User \u003c ApplicationRecord\n  validates_address if: -\u003e { something_changed? }, ...\nend\n```\n\nGeocode the address with:\n\n```ruby\nclass User \u003c ApplicationRecord\n  validates_address geocode: true, ...\nend\n```\n\nThe `latitude` and `longitude` fields are used by default. Specify the fields with:\n\n```ruby\nclass User \u003c ApplicationRecord\n  validates_address geocode: {latitude: :lat, longitude: :lon}, ...\nend\n```\n\nEmpty addresses are not verified. To require an address, add your own validation.\n\n```ruby\nclass User \u003c ApplicationRecord\n  validates :street, presence: true\nend\n```\n\n## SmartyStreets\n\nWith SmartyStreets, you must pass the country for non-US addresses.\n\n```ruby\nMainStreet::AddressVerifier.new(address, country: \"France\")\n```\n\nHere’s the list of [supported countries](https://smartystreets.com/docs/cloud/international-street-api#countries). You can pass the name, ISO-3, ISO-2, or ISO-N code (like `France`, `FRA`, `FR`, or `250`).\n\nFor Active Record, use:\n\n```ruby\nclass User \u003c ApplicationRecord\n  validates_address country: \"France\", ...\nend\n```\n\nOr use a proc to make it dynamic\n\n```ruby\nclass User \u003c ApplicationRecord\n  validates_address country: -\u003e { country }, ...\nend\n```\n\n## Internationalization (i18n)\n\nYou can customize error messages with the [i18n](https://github.com/ruby-i18n/i18n) gem. In Rails, add to the appropriate `config/locales` file:\n\n```yml\nen:\n  mainstreet:\n    errors:\n      messages:\n        unconfirmed: Address can't be confirmed\n        apt_unconfirmed: Apartment or suite can't be confirmed\n        apt_missing: Apartment or suite is missing\n```\n\n## Data Protection\n\nWe recommend encrypting street information and postal code (at the very least) for user addresses. [Lockbox](https://github.com/ankane/lockbox) is great for this. Check out [this article](https://ankane.org/sensitive-data-rails) for more details.\n\n```ruby\nclass User \u003c ApplicationRecord\n  has_encrypted :street, :postal_code\nend\n```\n\n## History\n\nView the [changelog](https://github.com/ankane/mainstreet/blob/master/CHANGELOG.md)\n\n## Contributing\n\nEveryone is encouraged to help improve this project. Here are a few ways you can help:\n\n- [Report bugs](https://github.com/ankane/mainstreet/issues)\n- Fix bugs and [submit pull requests](https://github.com/ankane/mainstreet/pulls)\n- Write, clarify, or fix documentation\n- Suggest or add new features\n\nTo get started with development:\n\n```sh\ngit clone https://github.com/ankane/mainstreet.git\ncd mainstreet\nbundle install\nbundle exec rake test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankane%2Fmainstreet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fankane%2Fmainstreet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankane%2Fmainstreet/lists"}