adressevaelger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39ce3fca5b50b066546e6325522fb11677182fc4cf9a766a6baa138c937e0860
+  data.tar.gz: d01d7d4289c3a52997c744bade5d6c094f398b52547a7135964c06d87774dcc8
+SHA512:
+  metadata.gz: 362d1a947156be0ecf9f8914596388136382e30748fd62289e13eaf05a836584092a9abd70bc86f9bb37a065451699e4ca310c8a0441f7fddcfdefc8d4528226
+  data.tar.gz: 875591926ea41fcfb4ada343652cd567c47a4d43e668f994e853318278a6641196daaececc21921c585fc23dbff357732139d98f6ff44d5d27931acb0c79975f

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial public release: Adressevælger client (`autocomplete` / `search`),
+  resolve by husnummer or adresse id, Adressevask `validate` / `vask`, and
+  optional ETRS89→WGS84 via soft-required `rgeo-proj4`.
+- VCR cassettes for husnummer search and resolve (tokens redacted).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rasmus Bergholdt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+# Adressevaelger
+
+Ruby client for Klimadatastyrelsen **Adressevælger** and **Adressevask**
+(Danmarks Adresseregister / DAR). Denmark only — no multi-country router,
+manual entry adapter, or commercial geocoder fallback.
+
+## Install
+
+```ruby
+# Gemfile
+gem "adressevaelger"
+
+# Optional: fill ResolvedAddress#latitude / #longitude from ETRS89
+gem "rgeo-proj4"
+```
+
+```sh
+bundle add adressevaelger
+# or: gem install adressevaelger
+```
+
+Requires Ruby 3.3+. No Rails dependency.
+
+## Usage
+
+```ruby
+require "adressevaelger"
+
+client = Adressevaelger::Client.new(
+  token: ENV.fetch("ADRESSEVAELGER_TOKEN") # or rely on demo default locally
+)
+
+# Autocomplete / search (min 3 characters)
+suggestions = client.autocomplete("Vestergade 1")
+suggestions.first.id    # => DAR husnummer id
+suggestions.first.label # => "Vestergade 1, 1456 København K"
+
+# Resolve husnummer or adresse by id
+resolved = client.resolve(id: suggestions.first.id, type: "husnummer")
+resolved.line1          # => "Vestergade 1"
+resolved.postal_code   # => "1456"
+resolved.coord_easting  # => ETRS89/UTM32N
+resolved.latitude       # => WGS84 if rgeo-proj4 is installed, else nil
+
+# Adressevask (free-text wash)
+washed = client.validate("vestergade 1 københavn")
+# alias: client.vask(...)
+```
+
+Environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `ADRESSEVAELGER_TOKEN` | API token (preferred over the demo default) |
+| `ADRESSEVAELGER_BASE_URL` | Override host (default `https://adressevaelger.dk`) |
+
+## Optional ETRS89 → WGS84
+
+`Adressevaelger::Etrs89ToWgs84` soft-requires [`rgeo-proj4`](https://github.com/rgeo/rgeo-proj4).
+If PROJ is unavailable, `resolve` still returns ETRS89 easting/northing and leaves
+WGS84 latitude/longitude `nil`.
+
+```ruby
+Adressevaelger::Etrs89ToWgs84.available? # => true/false
+lat, lon = Adressevaelger::Etrs89ToWgs84.call(easting: 724_533.07, northing: 6_176_026.84)
+```
+
+## Token notes
+
+The Adressevælger HTTP API requires a `token` query parameter. Until Brugerstyring
+lands, Klimadatastyrelsen documents a shared demo token for exploration. The gem
+falls back to that demo token when none is configured — **do not rely on it in
+production**. Obtain a proper token via [Dataforsyningen](https://dataforsyningen.dk/).
+
+## Testing
+
+```sh
+bundle exec rake test
+```
+
+HTTP integration tests use [VCR](https://github.com/vcr/vcr) cassettes recorded
+against the real API (tokens redacted). CI uses `record: :none` (fail-closed).
+To refresh cassettes locally:
+
+```sh
+VCR_RECORD=all bundle exec rake test TEST=test/client_vcr_test.rb
+```
+
+Never hand-write cassette response bodies.
+
+## Scope
+
+**In:** Adressevælger search/autocomplete, resolve by husnummer/adresse id,
+Adressevask validate, optional PROJ transform.
+
+**Out:** Multi-country routing, Manual adapters, commercial fallback geocoders,
+Rails controllers/Stimulus, CRM persistence helpers.
+
+## Attribution
+
+Address data via [Dataforsyningen](https://dataforsyningen.dk/) /
+Klimadatastyrelsen Adressevælger and Adressevask. This gem is an independent
+open-source client and is not affiliated with or endorsed by Klimadatastyrelsen.
+
+## Releasing
+
+Version bumps are intentional — CI does not auto-bump on every `main` push.
+
+1. Bump `Adressevaelger::VERSION` in `lib/adressevaelger/version.rb` (gemspec reads it).
+2. Update `CHANGELOG.md` for that version.
+3. Commit and push to `main`.
+4. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`
+   (or create a GitHub Release for `vX.Y.Z` — that also pushes the tag).
+5. Tag **must** match the gem version (`v0.1.0` ↔ `0.1.0`). The
+   [push_gem](.github/workflows/push_gem.yml) workflow verifies this, then
+   publishes via [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/)
+   (`rubygems/release-gem`, OIDC — no `RUBYGEMS_API_KEY` secret).
+
+### One-time RubyGems Trusted Publisher setup
+
+The gem is not on RubyGems yet, so use a **pending** trusted publisher
+(Rasmus must click through the UI; no credentials belong in this repo):
+
+1. Sign in at [rubygems.org](https://rubygems.org/) (MFA on).
+2. Open [Pending trusted publishers](https://rubygems.org/profile/oidc/pending_trusted_publishers).
+3. Click **Create**.
+4. Fill in:
+   - **Gem name:** `adressevaelger`
+   - **Repository owner:** `bergholdt`
+   - **Repository name:** `adressevaelger`
+   - **Workflow filename:** `push_gem.yml`
+   - **Environment name:** `release`
+5. Click **Create Pending trusted publisher**.
+6. In GitHub → repo **Settings → Environments**, create an environment named
+   `release` (no required reviewers needed for a solo maintainer).
+
+After the first successful tag-triggered publish, the pending publisher becomes
+a normal trusted publisher and you own the gem on RubyGems.org.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/adressevaelger.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/adressevaelger/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "adressevaelger"
+  spec.version = Adressevaelger::VERSION
+  spec.authors = ["Rasmus Bergholdt"]
+  spec.email = ["rasmus.bergholdt@gmail.com"]
+
+  spec.summary = "Ruby client for Klimadatastyrelsen Adressevælger and Adressevask (DAR)."
+  spec.description = <<~DESC
+    HTTP client for the Danish Adressevælger autocomplete/search and Adressevask
+    address-wash APIs (Danmarks Adresseregister / DAR), with an optional
+    ETRS89/UTM32N → WGS84 helper via PROJ.
+  DESC
+  spec.homepage = "https://github.com/bergholdt/adressevaelger"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/bergholdt/adressevaelger/tree/v#{spec.version}"
+  spec.metadata["changelog_uri"] = "https://github.com/bergholdt/adressevaelger/blob/v#{spec.version}/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/bergholdt/adressevaelger/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.start_with?(*%w[bin/ test/ .git .github Gemfile Rakefile])
+    end
+  end
+  spec.require_paths = ["lib"]
+end

data/lib/adressevaelger/client.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+require_relative "suggestion"
+require_relative "resolved_address"
+
+module Adressevaelger
+  # HTTP client for Klimadatastyrelsen Adressevælger (+ Adressevask).
+  #
+  # Official host is adressevaelger.dk (api.adressevaelger.dk does not resolve).
+  class Client
+    # Token is required by the API. Until Brugerstyring lands, KDS recommends
+    # this shared demo token for exploration — replace it in production.
+    DEFAULT_TOKEN = "adressevaelger123"
+    DEFAULT_BASE_URL = "https://adressevaelger.dk"
+    EPSG = 25832
+
+    attr_reader :base_url, :token
+
+    def initialize(token: nil, base_url: nil, http: nil)
+      @token = present_string(token) || present_string(ENV["ADRESSEVAELGER_TOKEN"]) || DEFAULT_TOKEN
+      @base_url = present_string(base_url) || present_string(ENV["ADRESSEVAELGER_BASE_URL"]) || DEFAULT_BASE_URL
+      @http = http
+    end
+
+    # Autocomplete husnumre by free-text query (min 3 characters).
+    def autocomplete(query)
+      return [] if blank?(query) || query.to_s.length < 3
+
+      payload = get_json("/husnumre/soeg", tekst: query)
+      Array(payload["fund"]).filter_map do |fund|
+        next unless present?(fund["id"]) && present?(fund["titel"])
+
+        Suggestion.from_fund(fund)
+      end
+    end
+
+    # Alias used by callers that think in "search" terms.
+    alias search autocomplete
+
+    # Resolve a husnummer or adresse by DAR id.
+    def resolve(id:, type: "husnummer")
+      path = case type.to_s
+      when "adresse" then "/adresser/#{id}"
+      else "/husnumre/#{id}"
+      end
+
+      payload = get_json(path)
+      build_resolved(payload, type: type.to_s)
+    end
+
+    # Wash / validate a free-text address via Adressevask (`/vask/`).
+    def validate(text)
+      return [] if blank?(text)
+
+      payload = get_json("/vask/", adresse: text)
+      results = Array(payload["resultater"] || payload["fund"] || payload["adresser"])
+      results.filter_map do |row|
+        id = row["adresse_id_lokalid"] || row["id"] || dig_hash(row, "adresse", "id")
+        label = row["betegnelse"] || row["titel"] || row["adressebetegnelse"]
+        next if blank?(id) || blank?(label)
+
+        Suggestion.new(
+          id: id,
+          type: present_string(row["type"]) || "adresse",
+          label: label,
+          provider: Adressevaelger::PROVIDER
+        )
+      end
+    end
+
+    # Alias matching the Adressevask product name.
+    alias vask validate
+
+    private
+
+      attr_reader :http
+
+      def build_resolved(payload, type:)
+        data = nested_entity(payload)
+        vejnavn = scalar(pick(data, "vejnavn")) || dig_hash(data, "vejstykke", "navn") || dig_hash(data, "navngivenvej", "vejnavn")
+        husnr = scalar(pick(data, "husnr", "husnummertekst", "husnummer"))
+        postal = scalar(pick(data, "postnr")) || dig_hash(data, "postnummer", "postnr") || dig_hash(data, "postnummer", "nr")
+        city = scalar(pick(data, "postnrnavn", "bynavn")) || dig_hash(data, "postnummer", "navn")
+        etage = scalar(pick(data, "etagebetegnelse", "etage"))
+        doer = scalar(pick(data, "doerbetegnelse", "dør", "doer"))
+
+        point = data["adgangspunkt"] || dig_hash(data, "adgangsadresse", "adgangspunkt") || data["position"]
+        easting, northing = extract_etrs89(point)
+        latitude, longitude = transform_etrs89(easting, northing)
+
+        id = pick(data, "id", "id_lokalid")
+        husnummer_id = pick(data, "husnummer_id", "adgangsadresseid") || (type == "husnummer" ? id : nil)
+        adresse_id = type == "adresse" ? id : pick(data, "adresse_id")
+
+        ResolvedAddress.new(
+          line1: [vejnavn, husnr].compact.reject { |part| blank?(part) }.join(" "),
+          line2: nil,
+          postal_code: postal.to_s,
+          city: city.to_s,
+          country: "DK",
+          etage: etage,
+          doer: doer,
+          address_provider: Adressevaelger::PROVIDER,
+          external_address_id: adresse_id || husnummer_id,
+          external_building_id: husnummer_id,
+          latitude: latitude,
+          longitude: longitude,
+          coord_easting: easting,
+          coord_northing: northing,
+          coord_epsg: easting ? EPSG : nil
+        )
+      end
+
+      def nested_entity(payload)
+        %w[data husnummer adresse].each do |key|
+          value = payload[key]
+          return value if value.is_a?(Hash)
+        end
+        payload
+      end
+
+      def pick(hash, *keys)
+        keys.each do |key|
+          value = hash[key]
+          return value if present?(value)
+        end
+        nil
+      end
+
+      def dig_hash(hash, *keys)
+        return nil unless hash.is_a?(Hash)
+
+        hash.dig(*keys)
+      end
+
+      def scalar(value)
+        return nil if blank?(value) || value.is_a?(Hash) || value.is_a?(Array)
+
+        value
+      end
+
+      def extract_etrs89(point)
+        return [nil, nil] if blank?(point)
+
+        if point.is_a?(Array) && point.size >= 2
+          return [point[0].to_f, point[1].to_f]
+        end
+
+        coords = point["koordinater"] || point["coordinates"] || point["position"] || dig_hash(point, "geometri", "coordinates")
+        if coords.is_a?(Array) && coords.size >= 2
+          return [coords[0].to_f, coords[1].to_f]
+        end
+        if coords.is_a?(Hash)
+          easting = coords["x"] || coords["øst"] || coords["oest"] || coords["easting"]
+          northing = coords["y"] || coords["nord"] || coords["northing"]
+          return [easting.to_f, northing.to_f] if present?(easting) && present?(northing)
+        end
+
+        easting = point["øst"] || point["oest"] || point["easting"] || point["x"]
+        northing = point["nord"] || point["northing"] || point["y"]
+        return [nil, nil] if blank?(easting) || blank?(northing)
+
+        [easting.to_f, northing.to_f]
+      end
+
+      # Wired when optional rgeo-proj4 / PROJ is available; otherwise leave WGS84 nil.
+      def transform_etrs89(easting, northing)
+        return [nil, nil] if easting.nil? || northing.nil?
+
+        Adressevaelger::Etrs89ToWgs84.call(easting: easting, northing: northing) || [nil, nil]
+      end
+
+      def get_json(path, params = {})
+        uri = URI.join("#{base_url}/", path.delete_prefix("/"))
+        query = params.merge(token: token).compact
+        uri.query = URI.encode_www_form(query)
+
+        request = Net::HTTP::Get.new(uri)
+        request["Accept"] = "application/json"
+        request["User-Agent"] = "Adressevaelger/#{VERSION}"
+
+        response = perform(uri, request)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise ProviderError, "Adressevælger error (#{response.code})"
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise ProviderError, "Adressevælger returned invalid JSON"
+      end
+
+      def perform(uri, request)
+        if http
+          return http.call(uri, request)
+        end
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 10) do |client|
+          client.request(request)
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, SocketError, Socket::ResolutionError => e
+        raise ProviderError, "Adressevælger unreachable (#{e.class})"
+      end
+
+      def blank?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+          (value.is_a?(String) && value.strip.empty?)
+      end
+
+      def present?(value)
+        !blank?(value)
+      end
+
+      def present_string(value)
+        return nil if blank?(value)
+
+        value.to_s
+      end
+  end
+end

data/lib/adressevaelger/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Adressevaelger
+  Error = Class.new(StandardError)
+  # Raised when the Adressevælger HTTP API fails, returns invalid JSON, or is unreachable.
+  ProviderError = Class.new(Error)
+end

data/lib/adressevaelger/etrs89_to_wgs84.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Adressevaelger
+  # ETRS89/UTM32N (EPSG:25832) → WGS84 (EPSG:4326) via PROJ (`rgeo-proj4`).
+  #
+  # Soft-requires `rgeo/proj4`. Returns `nil` when the optional gem is not
+  # installed or PROJ cannot load; resolve still returns ETRS89 easting/northing.
+  module Etrs89ToWgs84
+    module_function
+
+    def available?
+      return @available if defined?(@available)
+
+      begin
+        require "rgeo/proj4"
+        @source = RGeo::CoordSys::Proj4.create(25832)
+        @target = RGeo::CoordSys::Proj4.create(4326)
+        @available = true
+      rescue LoadError, StandardError
+        @available = false
+      end
+    end
+
+    def call(easting:, northing:)
+      return nil unless available?
+
+      lon, lat = RGeo::CoordSys::Proj4.transform_coords(
+        @source,
+        @target,
+        easting.to_f,
+        northing.to_f,
+        nil
+      )
+
+      [lat.round(7), lon.round(7)]
+    end
+  end
+end

data/lib/adressevaelger/resolved_address.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Adressevaelger
+  # Provider-shaped resolved Danish address (no host-app persistence helpers).
+  ResolvedAddress = Data.define(
+    :line1,
+    :line2,
+    :postal_code,
+    :city,
+    :country,
+    :etage,
+    :doer,
+    :address_provider,
+    :external_address_id,
+    :external_building_id,
+    :latitude,
+    :longitude,
+    :coord_easting,
+    :coord_northing,
+    :coord_epsg
+  )
+end

data/lib/adressevaelger/suggestion.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Adressevaelger
+  PROVIDER = "adressevaelger"
+
+  # Autocomplete / vask hit from Adressevælger or Adressevask.
+  Suggestion = Data.define(:id, :type, :label, :provider) do
+    def self.from_fund(fund)
+      new(
+        id: fund.fetch("id"),
+        type: fund.fetch("type"),
+        label: fund.fetch("titel"),
+        provider: Adressevaelger::PROVIDER
+      )
+    end
+  end
+end

data/lib/adressevaelger/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Adressevaelger
+  VERSION = "0.1.0"
+end

data/lib/adressevaelger.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "adressevaelger/version"
+require_relative "adressevaelger/error"
+require_relative "adressevaelger/suggestion"
+require_relative "adressevaelger/resolved_address"
+require_relative "adressevaelger/etrs89_to_wgs84"
+require_relative "adressevaelger/client"
+
+# Ruby client for Klimadatastyrelsen Adressevælger + Adressevask (DAR).
+#
+# Denmark only. Country routing, manual entry, and commercial geocoders belong
+# in the host application.
+module Adressevaelger
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: adressevaelger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rasmus Bergholdt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  HTTP client for the Danish Adressevælger autocomplete/search and Adressevask
+  address-wash APIs (Danmarks Adresseregister / DAR), with an optional
+  ETRS89/UTM32N → WGS84 helper via PROJ.
+email:
+- rasmus.bergholdt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- adressevaelger.gemspec
+- lib/adressevaelger.rb
+- lib/adressevaelger/client.rb
+- lib/adressevaelger/error.rb
+- lib/adressevaelger/etrs89_to_wgs84.rb
+- lib/adressevaelger/resolved_address.rb
+- lib/adressevaelger/suggestion.rb
+- lib/adressevaelger/version.rb
+homepage: https://github.com/bergholdt/adressevaelger
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bergholdt/adressevaelger
+  source_code_uri: https://github.com/bergholdt/adressevaelger/tree/v0.1.0
+  changelog_uri: https://github.com/bergholdt/adressevaelger/blob/v0.1.0/CHANGELOG.md
+  bug_tracker_uri: https://github.com/bergholdt/adressevaelger/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Ruby client for Klimadatastyrelsen Adressevælger and Adressevask (DAR).
+test_files: []