zipcodestack (Ruby SDK)

A lightweight Ruby client for the zipcodestack.com API.

Installation

Add this line to your application's Gemfile:

gem "zipcodestack"

And then execute:

bundle install

Or install it yourself as:

gem build zipcodestack.gemspec
gem install zipcodestack-$(ruby -e 'require "./lib/zipcodestack/version"; print Zipcodestack::Version::STRING').gem

Getting an API key

Create an account and obtain your API key from the dashboard. See the official docs: zipcodestack.com API Documentation.

Quick start

require "zipcodestack"

client = Zipcodestack::Client.new(
  api_key: ENV.fetch("ZIPCODESTACK_API_KEY"),
  # Set your API base according to the docs; examples:
  #   "https://api.zipcodestack.com" or "https://zipcodestack.com/api"
  api_base: ENV.fetch("ZIPCODESTACK_API_BASE", "https://api.zipcodestack.com"),
  # By default the client sends Authorization: Bearer <API_KEY>.
  # If you prefer API key via query params, set use_header_auth: false.
  use_header_auth: true
)

# Perform a search request (refer to official docs for supported parameters)
result = client.search(query: "90210", country: "US")
puts result

# Compute distance (refer to official docs for supported parameters)
distance = client.distance(from: "90210", to: "10001", unit: "mi")
puts distance

# You can also call arbitrary GET endpoints
raw = client.get("/status")
puts raw

Configuration

  • api_key: Your API key string.
  • api_base: The base URL for the API. Consult the docs to choose the correct host and path.
  • use_header_auth: If true, sends Authorization: Bearer <API_KEY>. If false, sends apikey=<API_KEY> as a query parameter.
  • open_timeout / read_timeout: Net::HTTP timeouts in seconds (defaults: 5s / 10s).
  • user_agent: Custom user agent (defaults to zipcodestack-ruby/<version>).

Error handling

Non-2xx HTTP responses raise Zipcodestack::HTTPError with status and body fields. Rescue as needed:

begin
  client.search(query: "00000")
rescue Zipcodestack::HTTPError => e
  warn "Request failed: #{e.status} #{e.message}"
end

Contributing

Bug reports and pull requests are welcome on GitHub. Please run tests and linters before submitting.

License

This gem is available as open source under the terms of the MIT License. See LICENSE.