overture_maps 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d14f7592823c00db641da88d4d89558758dfb67614a20b0d742401db4eabb233
+  data.tar.gz: 0112f6338b6245b8574328622300a44c8dfb83fd6d944be8cecd2ffc20daf27c
+SHA512:
+  metadata.gz: c959c7e964b4117b26faebd4bebe2685fa0eb251268eaac80fc2248aa2b5de260c333c96cf32a9419aaf3b7916c793a8e45caaa1c63a831d90c9ba8dc54389eb
+  data.tar.gz: 18046c68c4c724de398c925a15c03eb0edd9593d48eacc1394540700633de524848b30c5a2e79303478b28f8576e586a6b8fe93120416e4e32714106080ac6b7

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - 2026-07-12
+
+Initial release.
+
+### Added
+
+- Location-based imports for all six Overture themes (places, buildings,
+  addresses, divisions, transportation, base) into PostGIS: bbox-filtered
+  GeoParquet extracts via DuckDB with row-group pushdown, idempotent
+  `upsert_all` imports keyed on GERS ids, and shared extract caching.
+- Division geocoding (`rails overture_maps:import:places[Seattle]`) with
+  local-first resolution once divisions are imported.
+- Ad-hoc query API (`OvertureMaps.query`) over remote or cached GeoParquet —
+  counts, streaming, GeoJSON/GPKG exports — with no database required.
+- Release discovery via Overture's STAC catalog; changelog-driven syncing
+  (`rails overture_maps:sync`) that applies removals and upserts instead of
+  full reloads; GERS registry lookups.
+- Category taxonomy with group expansion (`eat_and_drink` → leaf categories).
+- Mountable REST engine: JSON/GeoJSON feature endpoints with keyset
+  pagination, division search, license-correct attribution notices, and
+  Mapbox Vector Tiles straight from PostGIS (`ST_AsMVT`).
+- `overture-maps-mcp`: a read-only MCP server over the public Overture
+  bucket (geocode, query/count features, GeoJSON export, GERS lookup).
+- Install generator creating migrations, models, and the engine mount.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Overture Maps
+
+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,416 @@
+# Overture Maps Ruby Gem
+
+A Ruby gem for integrating with [Overture Maps](https://overturemaps.org/) — an open map data foundation providing geospatial data. Download bbox-filtered extracts of Overture GeoParquet data, import them into your Rails application's PostGIS database, serve them through ActiveRecord, a mountable REST API, or vector tiles, and keep them current with changelog-driven syncs. Or skip the database entirely: query the bucket ad hoc from Ruby, or hand AI assistants the bundled MCP server.
+
+This is an unofficial community gem, not a product of the Overture Maps Foundation.
+
+## Features
+
+- **Location-based import**: `rails overture_maps:import:places[Seattle]` — searches Overture divisions by name, downloads a bbox-filtered extract, and upserts it into PostGIS
+- **All six Overture themes**: places, buildings, addresses, divisions, transportation, and base, with category filters backed by the full ~2,100-entry Overture taxonomy
+- **Efficient remote access**: DuckDB pushes bbox predicates down to parquet row-group statistics, so only the relevant slice of Overture's multi-hundred-GB datasets is transferred
+- **Idempotent imports**: rows are upserted by GERS id; re-running an import updates rather than fails
+- **Release-aware**: discovers the latest monthly Overture release via the official STAC catalog; extracts are cached per release and area
+- **Changelog-driven sync**: `rails overture_maps:sync` brings imported areas to the latest release by applying the official GERS changelog — no full reloads
+- **REST API**: a mountable engine serves imported data as JSON, GeoJSON, and Mapbox Vector Tiles, so MapLibre renders straight from your Rails app with no separate tile server
+- **Ad-hoc querying**: `OvertureMaps.query` counts, streams, and exports Overture data straight from the bucket — no import, no database
+- **MCP server**: `overture-maps-mcp` gives AI assistants read-only geocoding, query, and GeoJSON export tools over Overture's public data
+- **Rails integration**: model generators, spatial scopes, rake tasks, PostGIS utilities, RGeo geometries
+- **Attribution helpers**: builds the ODbL/CDLA notices your map is required to display from the imported source metadata
+
+## Installation
+
+Add to your Rails application's Gemfile:
+
+```ruby
+gem "overture_maps"
+
+# Recommended: native DuckDB bindings for the fastest remote queries.
+# Without this the gem falls back to the duckdb CLI (PATH lookup, then a
+# pinned download to ~/.cache/overture_maps).
+gem "duckdb"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Getting Started
+
+### Generate Models and Migrations
+
+```bash
+rails generate overture_maps:install
+rails db:migrate
+```
+
+This creates migrations for the PostGIS extension and the `overture_places`, `overture_buildings`, `overture_addresses`, `overture_categories`, `overture_divisions`, `overture_segments`/`overture_connectors`, and `overture_base_features` tables, plus their model files. Individual generators also exist: `overture_maps:place`, `overture_maps:building`, `overture_maps:address`, `overture_maps:division`, `overture_maps:transportation`, `overture_maps:base_features`.
+
+### Fetch Categories (Recommended)
+
+```bash
+rails overture_maps:categories:populate   # ~2,100 categories from the Overture taxonomy
+rails overture_maps:categories:list       # list all
+rails overture_maps:categories:primary    # list primary categories
+```
+
+## Importing Data
+
+```bash
+# By location name (searches Overture divisions; prompts if ambiguous)
+rails overture_maps:import:places[Seattle]
+rails "overture_maps:import:places[New York]"
+
+# By bounding box (underscore-separated lat/lng pairs)
+rails overture_maps:import:places[47.606_-122.336_47.609_-122.333]
+
+# Filter places by Overture leaf categories
+rails "overture_maps:import:places[Seattle,cafe]"
+rails "overture_maps:import:places[Seattle,cafe restaurant]"
+
+# Filter by taxonomy group (expands to leaf categories once
+# overture_maps:categories:populate has run)
+rails "overture_maps:import:places[Seattle,eat_and_drink]"
+
+# Other themes
+rails overture_maps:import:buildings[Seattle]
+rails overture_maps:import:addresses[Seattle]
+rails overture_maps:import:divisions[Washington]
+rails overture_maps:import:transportation[Seattle]
+rails overture_maps:import:base[Seattle]
+
+# Everything (resolves the location once, then imports each theme)
+rails overture_maps:import:all[Seattle]
+```
+
+Importing divisions has a bonus: once `overture_divisions` is populated,
+location-name searches resolve against your local database instead of
+querying Overture's bucket — imports and searches get much faster.
+
+How it works:
+
+1. The location is parsed as a bounding box, or matched against Overture division areas by name (you're prompted when several match).
+2. A bbox-filtered parquet extract is downloaded via DuckDB into `tmp/overture/`, named by theme, type, release, and area — reruns for the same release and area reuse it (you're prompted; non-interactive runs reuse automatically).
+3. Records are upserted in batches, keyed on their GERS id.
+
+Useful companions:
+
+```bash
+rails overture_maps:import:search[Seattle]   # see matching divisions first
+rails overture_maps:import:stats             # row counts per table
+OVERTURE_RELEASE=2026-05-21.0 rails overture_maps:import:places[Seattle]  # pin a release
+OVERTURE_NON_INTERACTIVE=1 ...               # never prompt (jobs/CI)
+IGNORE_ERRORS=1 ...                          # exit 0 despite row errors
+VERBOSE=1 ...                                # print row error details
+```
+
+## Downloading Data (without importing)
+
+```bash
+# Bbox extracts for a location, one file per feature type
+rails overture_maps:download:places[Seattle]
+rails overture_maps:download:buildings[47.606_-122.336_47.609_-122.333]
+
+# Explicit bbox / point + radius
+rails overture_maps:download:bbox[places,47.606,-122.336,47.609,-122.333]
+rails overture_maps:download:nearby[places,47.6062,-122.3321,5000]
+
+# Export formats other than parquet
+rails "overture_maps:download:bbox[places,47.6,-122.4,47.7,-122.2,place,,,geojson]"
+
+# Complete theme files (no location argument — very large!)
+rails overture_maps:download:places
+
+# Discovery
+rails overture_maps:download:versions          # available Overture releases
+rails overture_maps:download:themes            # themes and their feature types
+rails overture_maps:download:types[buildings]  # types present in the current release
+rails overture_maps:download:list[places]      # files without downloading
+rails overture_maps:download:search_divisions[Seattle]
+```
+
+### Data Structure
+
+Overture Maps data is organized by **theme** and **type**:
+
+| Theme | Types |
+|-------|-------|
+| addresses | address |
+| base | bathymetry, infrastructure, land, land_cover, land_use, water |
+| buildings | building, building_part |
+| divisions | division, division_area, division_boundary |
+| places | place |
+| transportation | connector, segment |
+
+All six themes can be imported and downloaded. Imports cover the types shown above except `building_part` (planned; needs the parent-building relationship). Division imports use `division_area` — the geocodable territories.
+
+## REST API
+
+The gem ships a mountable engine serving imported data as JSON, GeoJSON,
+and Mapbox Vector Tiles (the install generator adds the mount line):
+
+```ruby
+# config/routes.rb
+mount OvertureMaps::Engine => "/overture"
+```
+
+```
+GET /overture/places?bbox=-122.35,47.60,-122.33,47.62      # west,south,east,north
+GET /overture/places?near=47.609,-122.34,500&category=cafe
+GET /overture/buildings?q=tower&format=geojson             # FeatureCollection
+GET /overture/places/<gers-id>
+GET /overture/search?q=Seattle                             # division geocoding
+GET /overture/tiles/places/14/2624/5721.mvt                # vector tiles via ST_AsMVT
+```
+
+Resources: `places`, `buildings`, `addresses`, `divisions`, `segments`,
+`connectors`, `base_features`. Collections paginate by keyset — pass
+`meta.next_cursor` back as `?after=`. Limits are capped
+(`config.api_max_limit`), tile responses carry public cache headers, and
+everything is read-only.
+
+MapLibre can render imported data with no separate tile server:
+
+```js
+map.addSource("places", {
+  type: "vector",
+  tiles: ["https://your-app.example/overture/tiles/places/{z}/{x}/{y}.mvt"]
+});
+```
+
+The API is open by default; wrap it in your own auth:
+
+```ruby
+OvertureMaps.configure do |config|
+  config.api_auth = ->(controller) {
+    controller.head :unauthorized unless controller.request.headers["X-Api-Key"] == Rails.application.credentials.overture_api_key
+  }
+end
+```
+
+For public deployments, add rate limiting (e.g. Rack::Attack) in the host app.
+
+## Keeping Data Current
+
+Overture publishes a new release monthly. Every import records its area and
+release in `overture_imported_areas`, and syncing applies the official GERS
+changelog instead of a full reload — removed features are deleted, added and
+changed ones are upserted:
+
+```bash
+rails overture_maps:sync:status    # which areas are behind
+rails overture_maps:sync           # bring everything to the latest release
+rails overture_maps:sync[2026-06-17.0]   # or a specific release
+```
+
+Areas whose release is no longer in the catalog (Overture prunes old
+releases) get a full refresh automatically. Individual features can be
+traced through releases with the registry:
+
+```bash
+rails overture_maps:gers:lookup[1ef5ffe6-cea9-4d4d-98f3-efbedfa4a8d7]
+# first_seen, last_seen, last_changed, bbox, data file path
+```
+
+```ruby
+OvertureMaps::GERS.valid_id?(id)   # dashed UUID (current) or legacy 32-hex
+OvertureMaps::GERS.lookup(id)      # registry row or nil
+OvertureMaps::Changelog.counts(theme: "places", type: "place", release: "2026-06-17.0")
+```
+
+## Ad-hoc Querying (no import needed)
+
+Query Overture GeoParquet directly — DuckDB pushes the bbox filter down to
+row-group statistics, so even against the remote bucket only the relevant
+slice is read:
+
+```ruby
+# Count without downloading anything
+OvertureMaps.query(theme: "places", bbox: [47.5, -122.4, 47.7, -122.2]).count
+
+# Stream records (geometry parsed to RGeo features)
+OvertureMaps.query(theme: "places", location: "Seattle").limit(100).each do |record|
+  puts record.dig("names", "primary")
+end
+
+# Batches, GeoJSON, exports
+query = OvertureMaps.query(theme: "buildings", bbox: "47.5,-122.4,47.7,-122.2")
+query.each_batch(size: 500) { |batch| ... }
+query.limit(1000).to_geojson                 # FeatureCollection hash
+query.export("buildings.geojson")            # or .gpkg / .geojsonseq / .parquet
+
+# Multi-type themes need an explicit type
+OvertureMaps.query(theme: "transportation", type: "segment", location: "Seattle").count
+```
+
+Unlimited queries spool through the same cache files the import pipeline
+uses (`config.cache_dir`), so a query warms the cache for a later import and
+vice versa. Manage the cache with:
+
+```bash
+rails overture_maps:cache:list
+rails overture_maps:cache:clear            # everything
+rails overture_maps:cache:clear[seattle]   # matching extracts only
+```
+
+## Configuration
+
+```ruby
+# config/initializers/overture_maps.rb
+OvertureMaps.configure do |config|
+  config.release = "2026-06-17.0"   # pin a release (default: latest via STAC)
+  config.cache_dir = "tmp/overture" # where extracts are cached
+  config.batch_size = 1000          # import batch size
+  config.timeout = 30               # HTTP timeout in seconds
+  config.non_interactive = false    # never prompt (also OVERTURE_NON_INTERACTIVE=1)
+
+  # Point at a mirror (e.g. MinIO on your LAN) instead of Overture's bucket:
+  # config.s3_uri = "s3://my-mirror-bucket"
+  # config.s3_http_url = "https://my-mirror.example.com"
+end
+```
+
+## Programmatic Usage
+
+```ruby
+# Location-based import (what the rake tasks use)
+runner = OvertureMaps::Import::LocationBasedRunner.new(
+  theme: "places",
+  location: "Seattle",              # or "47.6_-122.4_47.7_-122.2", or a BoundingBox
+  model_class: OverturePlace,
+  categories: ["cafe"]
+).run
+runner.imported_count  # => 1234
+
+# File import with a custom transform (keyword or block)
+OvertureMaps::Import.run!(
+  theme: "places",
+  model_class: OverturePlace,
+  file_path: "/path/to/places.parquet"
+) do |record|
+  { id: record["id"], name: record.dig("names", "primary"), ... }
+end
+
+# Division search
+OvertureMaps::Import::Downloader.search_divisions(query: "Seattle")
+# => [{ id:, name:, subtype:, country:, region:, bbox:, area_km2: }, ...]
+
+# Read a local parquet extract
+reader = OvertureMaps::Import::ParquetReader.new
+reader.each_record(source: "/path/to/file.parquet") { |record| ... }
+```
+
+## Model Usage
+
+```ruby
+# Spatial scopes (all models)
+OverturePlace.within_bounds(47.5, -122.4, 47.7, -122.2)  # south, west, north, east
+OverturePlace.near(47.6062, -122.3321, 1000)             # lat, lng, radius in meters
+OverturePlace.first.to_geojson
+
+# Places
+OverturePlace.by_category("cafe")            # primary or alternate leaf category
+OverturePlace.by_brand("Starbucks")
+OverturePlace.by_country("US")
+OverturePlace.by_operating_status("open")
+OverturePlace.min_confidence(0.8)
+
+# Buildings
+OvertureBuilding.by_height(min: 50, max: 100)
+OvertureBuilding.by_floors(min: 10)
+OvertureBuilding.by_class("apartments")
+OvertureBuilding.with_height
+
+# Addresses
+OvertureAddress.by_country("US")
+OvertureAddress.by_locality("Seattle")
+OvertureAddress.by_postcode("98101")
+OvertureAddress.first.full_address
+
+# Divisions
+OvertureDivision.by_subtype("locality")
+OvertureDivision.search_by_name("Seattle").largest_first
+OvertureDivision.first.to_bounding_box
+
+# Transportation
+OvertureSegment.roads.by_class("motorway")
+OvertureSegment.rails
+OvertureConnector.near(47.6062, -122.3321, 500)
+
+# Base features
+OvertureBaseFeature.water
+OvertureBaseFeature.land_use.by_class("park")
+```
+
+## Database Utilities
+
+```ruby
+OvertureMaps::Database.postgis_available?
+OvertureMaps::Database.create_spatial_index(:overture_places)
+OvertureMaps::Database.bounding_box_query(:overture_places, south, west, north, east)
+OvertureMaps::Database.nearest_neighbors(:overture_places, lat, lng)
+```
+
+## MCP Server
+
+The gem ships `overture-maps-mcp`, a read-only [MCP](https://modelcontextprotocol.io)
+server over Overture's public data — no Rails app, no database. AI assistants
+get tools to geocode place names, query and count features, export GeoJSON,
+and look up GERS ids, all streaming from the bucket with bbox pushdown.
+
+```bash
+gem install overture_maps mcp
+```
+
+Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "overture-maps": { "command": "overture-maps-mcp" }
+  }
+}
+```
+
+Tools: `geocode`, `query_features`, `count_features`, `export_geojson`,
+`gers_lookup`, `list_releases`. The server is read-only and never touches
+your application database.
+
+## Attribution
+
+Overture data carries per-theme licenses (ODbL for OSM-derived themes, CDLA-Permissive-2.0 for places, per-source terms for addresses). The imported `sources` column preserves which upstream datasets contributed, and the gem turns that into the notices your app needs:
+
+```ruby
+OvertureMaps::Attribution.notices
+# => ["Overture Maps Foundation — overturemaps.org",
+#     "© OpenStreetMap contributors (ODbL)",
+#     "Data sources: Microsoft, meta"]
+OvertureMaps::Attribution.text   # one line for a map corner
+```
+
+Map UIs can fetch the same via `GET /overture/attribution`. See [docs.overturemaps.org/attribution](https://docs.overturemaps.org/attribution/) for the authoritative requirements.
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 7.0
+- PostgreSQL with PostGIS
+- DuckDB (the `duckdb` gem, a `duckdb` binary on PATH, or automatic CLI download)
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT License — see LICENSE.txt
+
+## Links
+
+- [Overture Maps](https://overturemaps.org/)
+- [Overture Maps Documentation](https://docs.overturemaps.org/)

data/app/controllers/overture_maps/application_controller.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  class ApplicationController < ActionController::API
+    before_action :authenticate!
+
+    rescue_from ArgumentError do |error|
+      render json: { error: error.message }, status: :bad_request
+    end
+
+    private
+
+    # Hosts wrap the API in their own auth:
+    #   OvertureMaps.configure do |c|
+    #     c.api_auth = ->(controller) {
+    #       controller.head :unauthorized unless controller.request.headers["X-Api-Key"] == ...
+    #     }
+    #   end
+    # Rendering or heading inside the hook halts the request.
+    def authenticate!
+      OvertureMaps.configuration.api_auth&.call(self)
+    end
+
+    def geojson?
+      params[:format] == "geojson" || request.headers["Accept"].to_s.include?("geo+json")
+    end
+  end
+end

data/app/controllers/overture_maps/attribution_controller.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # GET /overture/attribution — the notices required for the data this
+  # database actually holds. Map UIs can render these verbatim.
+  class AttributionController < ApplicationController
+    def index
+      expires_in 1.hour, public: true
+      render json: {
+        notices: Attribution.notices,
+        text: Attribution.text
+      }
+    end
+  end
+end

data/app/controllers/overture_maps/features_controller.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # Read-only access to imported Overture data.
+  #
+  #   GET /overture/places?bbox=-122.4,47.5,-122.2,47.7&category=cafe&limit=50
+  #   GET /overture/places?near=47.6,-122.3,1000&format=geojson
+  #   GET /overture/buildings/<gers-id>
+  #
+  # Collections paginate by keyset: pass meta.next_cursor back as ?after=.
+  # ?format=geojson (or Accept: application/geo+json) returns GeoJSON.
+  class FeaturesController < ApplicationController
+    RESOURCES = {
+      "places" => Models::Place,
+      "buildings" => Models::Building,
+      "addresses" => Models::Address,
+      "divisions" => Models::Division,
+      "segments" => Models::Segment,
+      "connectors" => Models::Connector,
+      "base_features" => Models::BaseFeature
+    }.freeze
+
+    MAX_RADIUS_METERS = 100_000
+
+    def index
+      scope = apply_filters(model.all)
+      scope = scope.where("id > ?", params[:after].to_s) if params[:after].present?
+      records = scope.order(:id).limit(page_size).to_a
+
+      if geojson?
+        render json: {
+          type: "FeatureCollection",
+          features: records.map(&:to_geojson)
+        }
+      else
+        render json: {
+          data: records.map { |record| serialize(record) },
+          meta: {
+            count: records.length,
+            next_cursor: records.length == page_size ? records.last&.id : nil
+          }
+        }
+      end
+    end
+
+    def show
+      record = model.find_by(id: params[:id])
+      return render json: { error: "not found" }, status: :not_found unless record
+
+      render json: geojson? ? record.to_geojson : serialize(record)
+    end
+
+    private
+
+    def model
+      RESOURCES.fetch(params[:resource])
+    end
+
+    def apply_filters(scope)
+      scope = filter_bbox(scope)
+      scope = filter_near(scope)
+      scope = filter_name(scope)
+      scope = filter_columns(scope)
+      scope = scope.by_category(params[:category].to_s.split(",")) if params[:category].present? && model == Models::Place
+      scope
+    end
+
+    def filter_bbox(scope)
+      return scope unless params[:bbox].present?
+
+      # GeoJSON bbox order: west,south,east,north
+      values = params[:bbox].split(",").map { |v| Float(v) }
+      raise ArgumentError, "bbox must be west,south,east,north" unless values.length == 4
+
+      west, south, east, north = values
+      unless south.between?(-90, 90) && north.between?(-90, 90) &&
+             west.between?(-180, 180) && east.between?(-180, 180)
+        raise ArgumentError, "bbox out of range"
+      end
+
+      scope.within_bounds(south, west, north, east)
+    end
+
+    def filter_near(scope)
+      return scope unless params[:near].present?
+
+      values = params[:near].split(",").map { |v| Float(v) }
+      raise ArgumentError, "near must be lat,lng[,radius_meters]" unless values.length.between?(2, 3)
+
+      lat, lng = values
+      radius = (values[2] || 1000).clamp(1, MAX_RADIUS_METERS)
+      raise ArgumentError, "near out of range" unless lat.between?(-90, 90) && lng.between?(-180, 180)
+
+      scope.near(lat, lng, radius)
+    end
+
+    def filter_name(scope)
+      return scope unless params[:q].present? && model.column_names.include?("name")
+
+      scope.where("name ILIKE ?", "%#{model.sanitize_sql_like(params[:q])}%")
+    end
+
+    def filter_columns(scope)
+      %w[country subtype operating_status].each do |column|
+        next unless params[column].present? && model.column_names.include?(column)
+
+        scope = scope.where(column => params[column])
+      end
+      scope
+    end
+
+    def page_size
+      requested = params[:limit].present? ? Integer(params[:limit]) : OvertureMaps.configuration.api_default_limit
+      raise ArgumentError, "limit must be positive" unless requested.positive?
+
+      [requested, OvertureMaps.configuration.api_max_limit].min
+    end
+
+    def serialize(record)
+      attributes = record.attributes.except("geometry")
+      attributes["geometry"] = record.geometry && RGeo::GeoJSON.encode(record.geometry)
+      attributes
+    end
+  end
+end

data/app/controllers/overture_maps/search_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # Division geocoding: GET /overture/search?q=Seattle
+  # Resolves from the local overture_divisions table when populated,
+  # falling back to Overture's bucket.
+  class SearchController < ApplicationController
+    def index
+      query = params[:q].to_s.strip
+      return render json: { error: "q is required" }, status: :unprocessable_entity if query.empty?
+
+      results = DivisionSearch.search(query: query)
+      render json: {
+        data: results.map do |result|
+          {
+            id: result[:id],
+            name: result[:name],
+            subtype: result[:subtype],
+            country: result[:country],
+            region: result[:region],
+            area_km2: result[:area_km2],
+            bbox: [result[:bbox].min_lng, result[:bbox].min_lat,
+                   result[:bbox].max_lng, result[:bbox].max_lat]
+          }
+        end
+      }
+    rescue OvertureMaps::Error => e
+      render json: { error: e.message }, status: :bad_gateway
+    end
+  end
+end