overture_maps 0.1.0

data/app/controllers/overture_maps/tiles_controller.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # Mapbox Vector Tiles straight from PostGIS:
+  #
+  #   GET /overture/tiles/places/14/2620/5723.mvt
+  #
+  # MapLibre/Leaflet can render imported data with no separate tile server:
+  #   map.addSource("places", { type: "vector",
+  #     tiles: ["https://app.example.com/overture/tiles/places/{z}/{x}/{y}.mvt"] })
+  class TilesController < ApplicationController
+    LAYERS = FeaturesController::RESOURCES
+
+    PROPERTY_COLUMNS = {
+      "places" => %w[name primary_category confidence country],
+      "buildings" => %w[name subtype building_class height num_floors],
+      "addresses" => %w[number street locality postcode],
+      "divisions" => %w[name subtype country],
+      "segments" => %w[name subtype segment_class],
+      "connectors" => %w[],
+      "base_features" => %w[name feature_type subtype feature_class]
+    }.freeze
+
+    MAX_ZOOM = 22
+    TILE_EXTENT = 4096
+    TILE_BUFFER = 64
+    # Half a buffer's worth of envelope margin so buffered geometries at the
+    # tile edge are included.
+    ENVELOPE_MARGIN = TILE_BUFFER.to_f / TILE_EXTENT
+
+    def show
+      layer = params[:layer]
+      model = LAYERS[layer]
+      return render json: { error: "unknown layer" }, status: :not_found unless model
+
+      z, x, y = tile_coordinates
+      tile = build_tile(model, layer, z, x, y)
+
+      expires_in 1.hour, public: true
+      send_data tile, type: "application/vnd.mapbox-vector-tile", disposition: "inline"
+    end
+
+    private
+
+    def tile_coordinates
+      z = Integer(params[:z])
+      x = Integer(params[:x])
+      y = Integer(params[:y])
+      max_index = (2**z) - 1
+      unless z.between?(0, MAX_ZOOM) && x.between?(0, max_index) && y.between?(0, max_index)
+        raise ArgumentError, "tile coordinates out of range"
+      end
+
+      [z, x, y]
+    end
+
+    def build_tile(model, layer, z, x, y)
+      connection = model.connection
+      columns = (PROPERTY_COLUMNS.fetch(layer, []) & model.column_names)
+                .map { |c| ", #{connection.quote_column_name(c)}" }.join
+
+      sql = ActiveRecord::Base.sanitize_sql(
+        [<<~SQL, { z: z, x: x, y: y, margin: ENVELOPE_MARGIN, limit: OvertureMaps.configuration.tile_feature_limit }]
+          WITH mvtgeom AS (
+            SELECT ST_AsMVTGeom(
+                     ST_Transform(geometry::geometry, 3857),
+                     ST_TileEnvelope(:z, :x, :y),
+                     #{TILE_EXTENT}, #{TILE_BUFFER}, true
+                   ) AS geom,
+                   id#{columns}
+            FROM #{model.quoted_table_name}
+            WHERE geometry && ST_Transform(ST_TileEnvelope(:z, :x, :y, margin => :margin), 4326)::geography
+            LIMIT :limit
+          )
+          SELECT ST_AsMVT(mvtgeom.*, #{connection.quote(layer)}, #{TILE_EXTENT}, 'geom')
+          FROM mvtgeom WHERE geom IS NOT NULL
+        SQL
+      )
+
+      value = connection.select_value(sql) || ""
+      # Raw query results may arrive as hex-escaped bytea.
+      value.start_with?("\\x") ? [value.delete_prefix("\\x")].pack("H*") : value
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+OvertureMaps::Engine.routes.draw do
+  resources_constraint = { resource: /places|buildings|addresses|divisions|segments|connectors|base_features/ }
+
+  get "search", to: "search#index"
+  get "attribution", to: "attribution#index"
+  get "tiles/:layer/:z/:x/:y", to: "tiles#show",
+                               constraints: { z: /\d+/, x: /\d+/, y: /\d+/ }
+
+  get ":resource", to: "features#index", constraints: resources_constraint
+  get ":resource/:id", to: "features#show", constraints: resources_constraint
+end

data/exe/overture-maps-mcp

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "overture_maps/mcp_server"
+
+OvertureMaps::MCPServer.start

data/lib/generators/overture_maps/address_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "generators/overture_maps/base_generator"
+
+module OvertureMaps
+  module Generators
+    class AddressGenerator < BaseGenerator
+      desc "Creates the overture_addresses table and model"
+
+      def create_migration
+        migration_template "address_migration.rb.tt", "db/migrate/create_overture_addresses.rb"
+      end
+
+      def create_model
+        template "address_model.rb.tt", "app/models/overture_address.rb"
+      end
+    end
+  end
+end

data/lib/generators/overture_maps/base_features_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "generators/overture_maps/base_generator"
+
+module OvertureMaps
+  module Generators
+    class BaseFeaturesGenerator < BaseGenerator
+      desc "Creates the overture_base_features table and model"
+
+      def create_migration
+        migration_template "base_features_migration.rb.tt", "db/migrate/create_overture_base_features.rb"
+      end
+
+      def create_model
+        template "base_feature_model.rb.tt", "app/models/overture_base_feature.rb"
+      end
+    end
+  end
+end

data/lib/generators/overture_maps/base_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module OvertureMaps
+  module Generators
+    class BaseGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      def self.default_source_root
+        File.expand_path("../templates", __dir__)
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/overture_maps/building_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "generators/overture_maps/base_generator"
+
+module OvertureMaps
+  module Generators
+    class BuildingGenerator < BaseGenerator
+      desc "Creates the overture_buildings table and model"
+
+      def create_migration
+        migration_template "building_migration.rb.tt", "db/migrate/create_overture_buildings.rb"
+      end
+
+      def create_model
+        template "building_model.rb.tt", "app/models/overture_building.rb"
+      end
+    end
+  end
+end

data/lib/generators/overture_maps/division_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "generators/overture_maps/base_generator"
+
+module OvertureMaps
+  module Generators
+    class DivisionGenerator < BaseGenerator
+      desc "Creates the overture_divisions table and model"
+
+      def create_migration
+        migration_template "division_migration.rb.tt", "db/migrate/create_overture_divisions.rb"
+      end
+
+      def create_model
+        template "division_model.rb.tt", "app/models/overture_division.rb"
+      end
+    end
+  end
+end

data/lib/generators/overture_maps/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "generators/overture_maps/base_generator"
+
+module OvertureMaps
+  module Generators
+    class InstallGenerator < BaseGenerator
+      desc "Creates the PostGIS extension, Overture tables, and model files"
+
+      def create_migrations
+        migration_template "postgis_migration.rb.tt", "db/migrate/create_overture_postgis.rb"
+        migration_template "category_migration.rb.tt", "db/migrate/create_overture_categories.rb"
+        migration_template "place_migration.rb.tt", "db/migrate/create_overture_places.rb"
+        migration_template "building_migration.rb.tt", "db/migrate/create_overture_buildings.rb"
+        migration_template "address_migration.rb.tt", "db/migrate/create_overture_addresses.rb"
+        migration_template "division_migration.rb.tt", "db/migrate/create_overture_divisions.rb"
+        migration_template "transportation_migration.rb.tt", "db/migrate/create_overture_transportation.rb"
+        migration_template "base_features_migration.rb.tt", "db/migrate/create_overture_base_features.rb"
+        migration_template "imported_areas_migration.rb.tt", "db/migrate/create_overture_imported_areas.rb"
+      end
+
+      def create_models
+        template "category_model.rb.tt", "app/models/overture_category.rb"
+        template "place_model.rb.tt", "app/models/overture_place.rb"
+        template "building_model.rb.tt", "app/models/overture_building.rb"
+        template "address_model.rb.tt", "app/models/overture_address.rb"
+        template "division_model.rb.tt", "app/models/overture_division.rb"
+        template "segment_model.rb.tt", "app/models/overture_segment.rb"
+        template "connector_model.rb.tt", "app/models/overture_connector.rb"
+        template "base_feature_model.rb.tt", "app/models/overture_base_feature.rb"
+      end
+
+      def add_engine_route
+        route <<~ROUTE.strip
+          # Overture Maps read-only API (JSON/GeoJSON + MVT tiles).
+          # Guard with config.api_auth in an initializer if the app is public.
+          mount OvertureMaps::Engine => "/overture"
+        ROUTE
+      end
+    end
+  end
+end

data/lib/generators/overture_maps/place_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "generators/overture_maps/base_generator"
+
+module OvertureMaps
+  module Generators
+    class PlaceGenerator < BaseGenerator
+      desc "Creates the overture_places table and model"
+
+      def create_migration
+        migration_template "place_migration.rb.tt", "db/migrate/create_overture_places.rb"
+      end
+
+      def create_model
+        template "place_model.rb.tt", "app/models/overture_place.rb"
+      end
+    end
+  end
+end

data/lib/generators/overture_maps/transportation_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "generators/overture_maps/base_generator"
+
+module OvertureMaps
+  module Generators
+    class TransportationGenerator < BaseGenerator
+      desc "Creates the overture_segments/overture_connectors tables and models"
+
+      def create_migration
+        migration_template "transportation_migration.rb.tt", "db/migrate/create_overture_transportation.rb"
+      end
+
+      def create_models
+        template "segment_model.rb.tt", "app/models/overture_segment.rb"
+        template "connector_model.rb.tt", "app/models/overture_connector.rb"
+      end
+    end
+  end
+end

data/lib/generators/templates/address_migration.rb.tt

@@ -0,0 +1,25 @@
+class CreateOvertureAddresses < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :overture_addresses, id: :string do |t|
+      t.string :number
+      t.string :street
+      t.string :unit
+      t.string :locality
+      t.string :region
+      t.string :postcode
+      t.string :country
+      t.string :postal_city
+      t.jsonb :address_levels, default: []
+      t.jsonb :sources, default: []
+      t.string :overture_release
+      t.timestamps
+    end
+
+    add_column :overture_addresses, :geometry, :st_point, geographic: true, srid: 4326
+    add_index :overture_addresses, :geometry, using: :gist
+
+    add_index :overture_addresses, :country
+    add_index :overture_addresses, :locality
+    add_index :overture_addresses, :postcode
+  end
+end

data/lib/generators/templates/address_model.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OvertureAddress < OvertureMaps::Models::Address
+end

data/lib/generators/templates/base_feature_model.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OvertureBaseFeature < OvertureMaps::Models::BaseFeature
+end

data/lib/generators/templates/base_features_migration.rb.tt

@@ -0,0 +1,27 @@
+class CreateOvertureBaseFeatures < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :overture_base_features, id: :string do |t|
+      t.string :feature_type, null: false
+      t.string :name
+      t.jsonb :names, default: {}
+      t.string :subtype
+      t.string :feature_class
+      t.string :surface
+      t.float :elevation
+      t.integer :level
+      t.string :wikidata
+      t.jsonb :source_tags, default: {}
+      t.jsonb :sources, default: []
+      t.string :overture_release
+      t.timestamps
+    end
+
+    # Base features span points, linestrings, and polygons.
+    add_column :overture_base_features, :geometry, :geometry, geographic: true, srid: 4326
+    add_index :overture_base_features, :geometry, using: :gist
+
+    add_index :overture_base_features, :feature_type
+    add_index :overture_base_features, :subtype
+    add_index :overture_base_features, :feature_class
+  end
+end

data/lib/generators/templates/building_migration.rb.tt

@@ -0,0 +1,24 @@
+class CreateOvertureBuildings < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :overture_buildings, id: :string do |t|
+      t.string :name
+      t.jsonb :names, default: {}
+      t.string :subtype
+      t.string :building_class
+      t.float :height
+      t.integer :num_floors
+      t.integer :level
+      t.boolean :is_underground, default: false
+      t.jsonb :sources, default: []
+      t.string :overture_release
+      t.timestamps
+    end
+
+    # Generic geography: building footprints are polygons/multipolygons.
+    add_column :overture_buildings, :geometry, :geometry, geographic: true, srid: 4326
+    add_index :overture_buildings, :geometry, using: :gist
+
+    add_index :overture_buildings, :height
+    add_index :overture_buildings, :building_class
+  end
+end

data/lib/generators/templates/building_model.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OvertureBuilding < OvertureMaps::Models::Building
+end

data/lib/generators/templates/category_migration.rb.tt

@@ -0,0 +1,15 @@
+class CreateOvertureCategories < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :overture_categories do |t|
+      t.string :name, null: false
+      t.string :primary_category
+      t.integer :hierarchy_level, default: 0
+      t.jsonb :taxonomy, default: []
+
+      t.timestamps
+    end
+
+    add_index :overture_categories, :name, unique: true
+    add_index :overture_categories, :primary_category
+  end
+end

data/lib/generators/templates/category_model.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OvertureCategory < OvertureMaps::Models::Category
+end

data/lib/generators/templates/connector_model.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OvertureConnector < OvertureMaps::Models::Connector
+end

data/lib/generators/templates/division_migration.rb.tt

@@ -0,0 +1,31 @@
+class CreateOvertureDivisions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :overture_divisions, id: :string do |t|
+      t.string :division_id
+      t.string :name
+      t.jsonb :names, default: {}
+      t.string :subtype
+      t.string :division_class
+      t.string :country
+      t.string :region
+      t.boolean :is_land
+      t.boolean :is_territorial
+      t.float :bbox_xmin
+      t.float :bbox_xmax
+      t.float :bbox_ymin
+      t.float :bbox_ymax
+      t.jsonb :sources, default: []
+      t.string :overture_release
+      t.timestamps
+    end
+
+    # Division areas are polygons/multipolygons.
+    add_column :overture_divisions, :geometry, :geometry, geographic: true, srid: 4326
+    add_index :overture_divisions, :geometry, using: :gist
+
+    add_index :overture_divisions, :name
+    add_index :overture_divisions, :subtype
+    add_index :overture_divisions, :country
+    add_index :overture_divisions, :division_id
+  end
+end

data/lib/generators/templates/division_model.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OvertureDivision < OvertureMaps::Models::Division
+end

data/lib/generators/templates/imported_areas_migration.rb.tt

@@ -0,0 +1,20 @@
+class CreateOvertureImportedAreas < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :overture_imported_areas do |t|
+      t.string :theme, null: false
+      t.string :feature_type, null: false
+      t.string :model_class_name, null: false
+      t.string :slug, null: false
+      t.float :bbox_xmin
+      t.float :bbox_xmax
+      t.float :bbox_ymin
+      t.float :bbox_ymax
+      t.string :release, null: false
+      t.integer :records_count, default: 0
+      t.timestamps
+    end
+
+    add_index :overture_imported_areas, [:theme, :feature_type, :slug], unique: true
+    add_index :overture_imported_areas, :release
+  end
+end

data/lib/generators/templates/place_migration.rb.tt

@@ -0,0 +1,30 @@
+class CreateOverturePlaces < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :overture_places, id: :string do |t|
+      t.string :name
+      t.jsonb :names, default: {}
+      t.jsonb :categories, default: {}
+      t.string :primary_category
+      t.jsonb :brands, default: {}
+      t.jsonb :addresses, default: []
+      t.jsonb :sources, default: []
+      t.jsonb :websites, default: []
+      t.jsonb :socials, default: []
+      t.jsonb :emails, default: []
+      t.jsonb :phones, default: []
+      t.decimal :confidence, precision: 3, scale: 2
+      t.string :operating_status
+      t.string :country
+      t.string :overture_release
+      t.timestamps
+    end
+
+    add_column :overture_places, :geometry, :st_point, geographic: true, srid: 4326
+    add_index :overture_places, :geometry, using: :gist
+
+    add_index :overture_places, :name
+    add_index :overture_places, :country
+    add_index :overture_places, :primary_category
+    add_index :overture_places, :categories, using: :gin
+  end
+end

data/lib/generators/templates/place_model.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OverturePlace < OvertureMaps::Models::Place
+end

data/lib/generators/templates/postgis_migration.rb.tt

@@ -0,0 +1,5 @@
+class CreateOverturePostgis < ActiveRecord::Migration<%= migration_version %>
+  def change
+    enable_extension "postgis"
+  end
+end

data/lib/generators/templates/segment_model.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OvertureSegment < OvertureMaps::Models::Segment
+end

data/lib/generators/templates/transportation_migration.rb.tt

@@ -0,0 +1,38 @@
+class CreateOvertureTransportation < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :overture_segments, id: :string do |t|
+      t.string :name
+      t.jsonb :names, default: {}
+      t.string :subtype
+      t.string :segment_class
+      t.string :subclass
+      t.jsonb :connectors, default: []
+      t.jsonb :routes, default: []
+      t.jsonb :speed_limits, default: []
+      t.jsonb :access_restrictions, default: []
+      t.jsonb :prohibited_transitions, default: []
+      t.jsonb :road_surface, default: []
+      t.jsonb :road_flags, default: []
+      t.jsonb :destinations, default: []
+      t.jsonb :sources, default: []
+      t.string :overture_release
+      t.timestamps
+    end
+
+    # Segments are linestrings.
+    add_column :overture_segments, :geometry, :geometry, geographic: true, srid: 4326
+    add_index :overture_segments, :geometry, using: :gist
+
+    add_index :overture_segments, :subtype
+    add_index :overture_segments, :segment_class
+
+    create_table :overture_connectors, id: :string do |t|
+      t.jsonb :sources, default: []
+      t.string :overture_release
+      t.timestamps
+    end
+
+    add_column :overture_connectors, :geometry, :st_point, geographic: true, srid: 4326
+    add_index :overture_connectors, :geometry, using: :gist
+  end
+end

data/lib/overture_maps/attribution.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  # Builds license-correct attribution from the data actually imported. The
+  # `sources` column preserved on every row records which upstream datasets
+  # contributed, which is what determines the required notices:
+  #
+  #   OvertureMaps::Attribution.notices  # => array of notice strings
+  #   OvertureMaps::Attribution.text     # => single line for a map corner
+  #
+  # Overture licensing: ODbL for OSM-derived themes (base, buildings,
+  # divisions, transportation), CDLA-Permissive-2.0 for places (Foursquare
+  # requires referencing their NOTICE), per-source terms for addresses.
+  # See https://docs.overturemaps.org/attribution/
+  module Attribution
+    FOURSQUARE_NOTICE_URL = "https://opensource.foursquare.com/places-notice-txt/"
+
+    class << self
+      def notices(models: default_models)
+        datasets = dataset_names(models: models)
+
+        notices = ["Overture Maps Foundation — overturemaps.org"]
+        notices << "© OpenStreetMap contributors (ODbL)" if datasets.any? { |d| d.match?(/openstreetmap|\bosm\b/i) }
+        if datasets.any? { |d| d.match?(/foursquare/i) }
+          notices << "Includes Foursquare data (CDLA-Permissive-2.0) — see #{FOURSQUARE_NOTICE_URL}"
+        end
+
+        remaining = datasets.reject { |d| d.match?(/openstreetmap|\bosm\b|foursquare/i) }
+        notices << "Data sources: #{remaining.sort.join(", ")}" if remaining.any?
+        notices
+      end
+
+      def text(models: default_models)
+        notices(models: models).join(" · ")
+      end
+
+      # Distinct upstream dataset names across the given models' sources
+      # columns.
+      def dataset_names(models: default_models)
+        models.flat_map { |model| datasets_for(model) }.uniq
+      end
+
+      def datasets_for(model)
+        return [] unless model.table_exists? && model.column_names.include?("sources")
+
+        model.connection.select_values(<<~SQL).compact
+          SELECT DISTINCT elem->>'dataset'
+          FROM #{model.quoted_table_name},
+               LATERAL jsonb_array_elements(sources) AS elem
+          WHERE sources IS NOT NULL AND jsonb_typeof(sources) = 'array'
+        SQL
+      rescue StandardError
+        []
+      end
+
+      private
+
+      def default_models
+        [
+          Models::Place, Models::Building, Models::Address, Models::Division,
+          Models::Segment, Models::Connector, Models::BaseFeature
+        ]
+      end
+    end
+  end
+end