alexreisner/geocoder · error · RuntimeError

region_code '# ' is invalid. use one of #…

Error message

region_code '#{region_code}' is invalid. use one of #{valid_region_codes}.https://developer.trimblemaps.com/restful-apis/location/single-search/single-search-api/#test-the-api-now

What it means

The PC*MILER lookup (Trimble Maps Single-Search API) only supports a fixed set of region codes (e.g. NA, EU, OC, SA). The lookup validates the region via valid_region_codes before building the request URL, and raises a plain RuntimeError if the configured region (from Geocoder config or the query) is not one of them.

Solutions

Set a valid region code in config: Geocoder.configure(pc_miler: {region: 'NA'}) (see valid_region_codes in lib/geocoder/lookups/pc_miler.rb for the exact accepted list).
Use the exact uppercase codes supported by the Trimble Single-Search API (NA, EU, OC, SA, etc.) rather than lowercase or full names.
If passing region per query, ensure the query options include the correct region value the lookup's region(query) method reads.
Verify the gem version's supported regions — Trimble has changed the API over time, so check the linked Single-Search API docs.

Example fix

// before
Geocoder.configure(lookup: :pc_miler, pc_miler: { region: 'usa' })
// after
Geocoder.configure(lookup: :pc_miler, pc_miler: { region: 'NA' })

Defensive patterns

Strategy: validation

Validate before calling

VALID_REGIONS = %w[NA EU OC SA].freeze # mirror valid_region_codes from lib/geocoder/lookups/pc_miler.rb
region = Geocoder.config[:pc_miler][:region]
raise ArgumentError, "pc_miler region #{region.inspect} invalid; use one of #{VALID_REGIONS}" unless VALID_REGIONS.include?(region)

Try / catch

begin
  Geocoder.search(address, lookup: :pc_miler)
rescue RuntimeError => e
  raise unless e.message.start_with?('region_code')
  Rails.logger.error("PC*MILER region misconfigured: #{e.message}")
  fallback_lookup_results
end

Prevention

Mirror valid_region_codes from the lookup file in your config validation at boot (e.g. an initializer asserting the region is valid).
Always use the uppercase Trimble region codes (NA, EU, OC, SA), never lowercase or full names.
Configure the region explicitly in Geocoder.configure instead of relying on defaults.
Pin and review gem versions when Trimble updates its API, and re-check the linked docs for the current region list.

When it happens

Trigger: Calling Geocoder.search(address, lookup: :pc_miler) or configuring Geocoder.configure(lookup: :pc_miler, pc_miler: {region: ...}) with a region code not in valid_region_codes (e.g. 'us', 'north_america', or a typo like 'N.A.').

Common situations: Default geocoder config left unset so region(query) returns nil; using lowercase or full-name region strings instead of the API's uppercase codes; copying config from another Trimble API that uses different region identifiers; region param passed per-query in the wrong form.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of alexreisner/geocoder@c10bd70121 (2026-09-15). Data as JSON: /api/errors/1d6679f9cd217b27. Report an issue: GitHub.

Appendix: source

Thrown at lib/geocoder/lookups/pc_miler.rb:30

      # EU: Europe
      # ME: Middle East
      # MX: Mexico
      # NA: North America
      # OC: Oceania
      # SA: South America
      %w[AF AS EU ME MX NA OC SA]
    end

    def name
      "PCMiler"
    end

    private # ---------------------------------------------------------------

    def base_query_url(query)
      region_code = region(query)
      if !valid_region_codes.include?(region_code)
        raise "region_code '#{region_code}' is invalid. use one of #{valid_region_codes}." \
          "https://developer.trimblemaps.com/restful-apis/location/single-search/single-search-api/#test-the-api-now"
      end

      "#{protocol}://singlesearch.alk.com/#{region_code}/api/search?"
    end

    def results(query)
      return [] unless data = fetch_data(query)
      if data['Locations']
        add_metadata_to_locations!(data)
        data['Locations']
      else
        []
      end
    end

    def add_metadata_to_locations!(data)
      confidence = data['QueryConfidence']

View on GitHub (pinned to c10bd70121)