zipcodestack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d7ad24f5015885f3629045a1c9a49a91f87d428f7cba2069ee3d9dfe19daa8b
+  data.tar.gz: 0cc66ec5e2a0042155dcdf4490153dff844f2cf4ec5c252afeaab094a6217da7
+SHA512:
+  metadata.gz: 2f2c5a6a8671d15a4645e333906856fcc5d7267c668bb80028b88b238e2e5bb54df050729baad64701b99679a9cfb2e15774b8009d34f937b8e20d08029ec572
+  data.tar.gz: cb85ed40e2451bda78d9436a9e6672b0c62c1b569eeb7d8a13c5ba6e2c97f7501d6e7158acda76686b06102809e31e2358887722db06bd940c798b31f87a694f

data/README.md

@@ -0,0 +1,88 @@
+# zipcodestack (Ruby SDK)
+
+A lightweight Ruby client for the `zipcodestack.com` API.
+
+- **Docs**: [zipcodestack.com API Documentation](https://zipcodestack.com/docs/)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "zipcodestack"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+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](https://zipcodestack.com/docs/).
+
+## Quick start
+
+```ruby
+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:
+
+```ruby
+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`.
+
+

data/lib/zipcodestack/client.rb

@@ -0,0 +1,132 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Zipcodestack
+  class Error < StandardError; end
+
+  class HTTPError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status:, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  class Client
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 10
+
+    attr_reader :api_key, :api_base, :use_header_auth, :open_timeout, :read_timeout, :user_agent
+
+    def initialize(api_key:, api_base:, use_header_auth: true, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT, user_agent: nil)
+      @api_key = api_key
+      @api_base = api_base.sub(/\/$/, "")
+      @use_header_auth = use_header_auth
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @user_agent = user_agent || default_user_agent
+    end
+
+    # Perform a GET request to an arbitrary path under the API base.
+    # params: Hash of query params
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    # Convenience: Search endpoint. Refer to API docs for supported parameters.
+    # Example params could include: { query: "90210", country: "US" }
+    def search(params = {})
+      get("/search", params)
+    end
+
+    # Convenience: Distance endpoint. Refer to API docs for supported parameters.
+    # Example params could include: { from: "90210", to: "10001", unit: "mi" }
+    def distance(params = {})
+      get("/distance", params)
+    end
+
+    private
+
+    def request(method, path, params: {})
+      uri = build_uri(path, params)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = open_timeout
+      http.read_timeout = read_timeout
+
+      request = build_http_request(method, uri)
+      attach_authentication(request, uri)
+      attach_headers(request)
+
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    def build_uri(path, params)
+      path = "/#{path}" unless path.start_with?("/")
+      uri = URI.parse("#{api_base}#{path}")
+
+      normalized_params = params.dup
+      unless use_header_auth
+        normalized_params = { apikey: api_key }.merge(normalized_params || {})
+      end
+
+      if normalized_params && !normalized_params.empty?
+        query = URI.encode_www_form(normalized_params)
+        uri.query = [uri.query, query].compact.join("&")
+      end
+      uri
+    end
+
+    def build_http_request(method, uri)
+      case method
+      when :get
+        Net::HTTP::Get.new(uri)
+      else
+        raise ArgumentError, "Unsupported method: #{method}"
+      end
+    end
+
+    def attach_authentication(request, _uri)
+      if use_header_auth
+        request["Authorization"] = "Bearer #{api_key}"
+      end
+    end
+
+    def attach_headers(request)
+      request["Accept"] = "application/json"
+      request["User-Agent"] = user_agent
+    end
+
+    def handle_response(response)
+      status = response.code.to_i
+      body = response.body
+
+      if status >= 200 && status < 300
+        parse_json(body)
+      else
+        message = begin
+          parsed = parse_json(body)
+          parsed.is_a?(Hash) && parsed["message"] || parsed["error"] || body
+        rescue JSON::ParserError
+          body
+        end
+        raise HTTPError.new("HTTP #{status}: #{message}", status: status, body: body)
+      end
+    end
+
+    def parse_json(string)
+      return nil if string.nil? || string.strip.empty?
+      JSON.parse(string)
+    end
+
+    def default_user_agent
+      "zipcodestack-ruby/#{Version::STRING} (Ruby #{RUBY_VERSION}; #{RUBY_PLATFORM})"
+    end
+  end
+end
+
+

data/lib/zipcodestack/version.rb

@@ -0,0 +1,7 @@
+module Zipcodestack
+  module Version
+    STRING = "0.1.0"
+  end
+end
+
+

data/lib/zipcodestack.rb

@@ -0,0 +1,7 @@
+require_relative "zipcodestack/version"
+require_relative "zipcodestack/client"
+
+module Zipcodestack
+end
+
+

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: zipcodestack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- zipcodestack SDK Maintainers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-09-30 00:00:00.000000000 Z
+dependencies: []
+description: A lightweight Ruby wrapper for the zipcodestack.com API, providing authentication
+  and convenient helpers.
+email:
+- support@zipcodestack.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/zipcodestack.rb
+- lib/zipcodestack/client.rb
+- lib/zipcodestack/version.rb
+homepage: https://zipcodestack.com/docs/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://zipcodestack.com/docs/
+  source_code_uri: https://github.com/zipcodestack/zipcodestack-ruby
+  changelog_uri: https://github.com/zipcodestack/zipcodestack-ruby/releases
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby client for the zipcodestack.com API
+test_files: []