Class: GeonamesRefreshWorker

Inherits:
Object
  • Object
show all
Includes:
Sidekiq::Job
Defined in:
app/workers/geonames_refresh_worker.rb

Overview

Monthly refresh of the postal_codes ZIP→state cache from the free GeoNames
dataset (https://download.geonames.org/export/zip/).

Covers the US (5-digit ZIPs, ~41k) and Canada (FSA-level — the free CA set is
first-3-char only, ~1.6k — which still gives accurate province, and notably
splits Nunavut from the Northwest Territories where the first-letter fallback
can't). PostalCode.state_for consults the FSA before that fallback.

Scheduled monthly (1st @ 3 AM CT) via sidekiq-scheduler. ZIP/FSA→state data is
very stable, so monthly proactively catches new codes while the on-read
self-heal (PostalCode.state_for) covers anything accessed in between. The
refresh is sanity-floored and an idempotent upsert-by-code (never deletes), so
a truncated/bad download can't corrupt the table —
PostalCodes::GeonamesRefresh::InsufficientData aborts the write and surfaces
loudly via Sidekiq/AppSignal rather than letting the cache silently rot (the
15-year-staleness this whole effort fixes).

On-demand: mise exec -- bin/rails 'postal_codes:refresh[ALL]' (DRY_RUN=1 to preview).

See Also:

Instance Method Summary collapse

Instance Method Details

#perform(countries = %w[US CA])) ⇒ Object

Parameters:

  • countries (Array<String>) (defaults to: %w[US CA])) —

    ISO-2 codes; defaults to US + Canada.



29
30
31
32
 
# File 'app/workers/geonames_refresh_worker.rb', line 29

def perform(countries = %w[US CA])
  total = PostalCodes::GeonamesRefresh.new(Array(countries)).run
  Rails.logger.info "[GeonamesRefreshWorker] Refreshed #{total} postal codes (#{Array(countries).join(', ')})"
end