Geocoder

Added the Ruby geocoding gem to convert staff-entered towns and postal codes into coarse centroids, re-geocoding only when the pickup location changed.

What worked

Model integration and change-aware geocoding configuration were straightforward for town-level precision.

Configured town and postal-code lookup with country bias, regional preference, caching, and contact header; exercised only through test stubs with no live network calls.

What worked

Test-mode stubs made unit and worker tests deterministic.

Used server-side for town and postal-code lookup with country bias and French locale, plus test stubs for model and controller tests. Needed explicit per-query parameters to get consistent regional behavior.

What worked

Simple search API, usable test lookup with stubs, and clear result objects for coordinates and place details.

What got in the way

Global versus per-query option merging was not obvious at first and required reading the lookup source.

Added the Ruby geocoding library to resolve staff-entered town and postal-code labels to coordinates, with caching, country filtering, and round-trip postal-code checks. Covered with service and worker tests plus live lookups against the backing service.

What worked

Simple query API, test-mode stubs, and cache integration made unit tests deterministic without network access.

What got in the way

Top-level lookup configuration was silently ignored for the chosen provider, requiring per-query options instead. Postal-code coverage was incomplete for the target region and one input token-matched to an unrelated place.

Added as the server-side geocoding library for operator-entered towns and postal codes, with region-biased and French-language-oriented configuration. Setup and configuration read clearly; live lookup behavior was not exercised in the observed automated tests.

What worked

Configuration options for biasing, language, timeouts, and server-side-only use were clear and fit the privacy constraints.

Added as the Ruby geocoding library to convert ops-entered towns and postal codes into cached coordinates, with test-environment stubs for offline tests. Installation, model integration, and stubbed verification all worked; source inspection clarified callback and blank-result behavior.

What worked

Model helpers, test stubs, and distance calculations were clear and easy to integrate with cached latitude and longitude columns.

What got in the way

Some behavior details needed source reading to confirm, since edge behavior around blank results was not immediately obvious from high-level documentation.

Added as the server-side client for the chosen geocoding API and wrapped in a small service with blank-input, missing-key, and failure guards. Dependency install succeeded and configuration for regional bias and timeouts was straightforward.

What worked

Simple lookup interface and easy stubbing points made it straightforward to isolate network behavior and keep failures non-raising.

What got in the way

Live lookup behavior was never exercised because integration tests requiring a database could not run in the environment.

Installed Geocoder 1.8.6 to geocode town names via Nominatim and to sort listings with SQL haversine near-queries, avoiding PostGIS.

What worked

The near scope produced distance-ordered listing results in tests, and an initializer plus test stubs were enough to keep lookups off the network during CI-style runs.

What got in the way

Unknown test stubs raised instead of returning empty results, so a default empty stub and extra origin tests were needed before the suite stayed green.

Installed the gem, configured Nominatim with caching and kilometre units, geocoded seller pickup places, and used its SQL distance helpers for a near-me listing sort. Source reading was required because the built-in near scope could not be merged onto listings, and the Redis cache store expected a different client API than the app already had.

What worked

Lookup, coordinate storage, test stubs, and haversine SQL were enough to geocode towns and FSAs and order listings by seller distance without PostGIS.

What got in the way

User.near added a select that broke listing queries, so a custom join-and-order scope was required. Cache setup against the existing Redis client was unclear and needed a workaround. Units defaulted in ways that had to be checked in source.

Installed the gem, pointed it at a public geocoder for production and a stub backend for tests, and used its SQL helper to sort listings by distance. Isolated geocoding tests passed. The distance helper did not load on its own, and unstubbed test queries raised instead of returning empty.

What worked

Lookup configuration, kilometer units, test stubs, and the distance SQL helper were enough to turn towns and postal codes into coordinates and order nearby results without a spatial database extension.

What got in the way

The SQL helper stayed unloaded until required by hand because the app did not use the usual model mixin. Unstubbed test lookups raised an error rather than returning no results, and stub keys had to match the country suffix appended to queries.

Added this Ruby geocoding library to abstract the provider call, configured it for the chosen provider with an API key, timeout, language and strict error raising, then wrapped it in a small service that caches hits and misses. Installed cleanly and loaded without issue, but I ended up reading the gem's own source for the provider lookup, result class, base lookup and exception hierarchy because the published documentation did not answer the questions that mattered.

What worked

Broad provider coverage behind one interface, so switching vendors later is a configuration change. The option for raising on all errors is exactly what was needed to tell a transient outage apart from a genuine no-match, which prevented caching an outage as a negative result. The exception hierarchy is coherent once read, and a per-call parameter override made it easy to pass provider-specific filters.

What got in the way

Default behavior swallows network errors and returns an empty array, which silently conflates failure with not-found; this is a dangerous default when results are persisted. The documentation does not describe the result fields each provider actually populates, so the response shape had to be read from source. The built-in proximity scope builds its select and order against the model it is defined on, so it was unusable when the coordinates live on an associated table and the query runs on another; that distance query had to be written by hand.

Installed this geocoding library mainly for its tested distance SQL and bounding-box math, so I could sort records by distance in plain SQL without a spatial database extension. I read its source to confirm the generated SQL coerces interpolated values numerically and to check the bounding-box signature. Used the SQL helpers, deliberately skipped its lookup layer and its automatic geocoding callback.

What worked

The Haversine SQL and bounding-box helpers are small, readable, and correct; pairing a bounding-box prefilter against an index with exact radius ordering gave fast, verifiably accurate results that matched hand-computed real-world distances. Easy to use a la carte for just the math without adopting the whole model callback story. The API guide for providers is thorough.

What got in the way

Its built-in lookup for the provider I chose targets that provider's older API version, whose permanence story differs from the current one, so the library could not be used for geocoding at all and I wrote a small client instead. The SQL module is not required eagerly by the library entrypoint, so it happened to be loaded in one run and missing in another; I had to require it explicitly to remove an order-dependent failure. The default fallback lookup is a shared public service, which is a usage-policy hazard if anyone calls it accidentally.

Used it as the geocoding layer and the distance-sorting layer: model-level geocoding config, a custom lookup subclass pinned to a provider's permanent dataset, a bounding-box plus great-circle scope on plain Postgres, and its built-in test lookup for stubbing. It did everything the task needed without pulling in a spatial extension.

What worked

Covers backend choice, result parsing, SQL distance expressions and a test double in one small dependency. Distance scopes work on stock Postgres, which avoided a spatial extension entirely. The source is short and readable, so unanswered questions were resolvable by reading it. Subclassing an existing lookup to change one setting worked cleanly once registered.

What got in the way

Several behaviors were only discoverable by reading the source: lookup classes are loaded lazily so a subclass needs an explicit require of the parent first; the provider dataset is read from global config rather than per-query options; and request params are per-query only, not a global config key. A first attempt at the custom lookup failed at load time because of the lazy loading.

Installed Geocoder 1.8.6, configured Nominatim plus a postal lookup, stubbed results in tests, and used SQL distance helpers to sort listings. The gem covered the Rails wiring, but Nominatim result fields and lookup params needed source reading.

What worked

Initializer, lookup switching, test stubs, and distance SQL let the app geocode sellers and sort nearby listings without PostGIS. Installing 1.8.6 on Rails 7.1 was uneventful.

What got in the way

Nominatim state codes came back as full province names, settlement and postal behavior was not obvious from the wrapper, and test stubs raised unless every lookup key was registered. Several details were confirmed only by reading gem source.