Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Geocoding and search providers

MapHub can use Free, OpenCage, or AWS geocoding. The available providers depend on the map owner’s plan and the providers configured on the MapHub installation.

The editor search provider applies when an editor searches for places while changing a map.

  • Maps owned by Free accounts use Free geocoding.
  • Hobbyist maps prefer OpenCage when it is configured.
  • Business maps prefer AWS when it is configured.
  • Enterprise installations use their configured providers.

If a preferred provider is unavailable, MapHub selects another available provider and always keeps Free geocoding as the fallback. Provider lists contain only known providers with configured credentials.

When several editor providers are available, an editor can save a default provider from Map → UI controls → Editor search provider. The choice belongs to the editor, not the map, and applies whenever that user edits a map whose owner plan makes the provider available. The provider menu beside the editor search box can temporarily override that default for the current page session. It survives map saves but can reset after full-page navigation. These controls are hidden when only one provider is available.

Visitor search belongs to the map and is separate from editor search.

  • Free maps cannot enable visitor search.
  • Hobbyist maps use Free geocoding for visitors.
  • Business and Enterprise map owners can select AWS, OpenCage, or Free when each provider is available to their installation.

The map owner can enable search for the normal map page or embeds under Map → UI controls. Both surfaces use the map’s provider choice. When several visitor providers are available, the owner can also select the visitor search provider there. An unavailable saved value falls back to the normal available default, or Free when no paid provider is available. Save the map after changing visitor settings. The server resolves this fallback when it loads the map; clients use the returned provider instead of applying their own provider policy.

An Enterprise installation uses the same per-user editor and per-map visitor choices as hosted Business accounts. It has no separate Enterprise editor list or default and no installation-wide visitor-provider setting. Legacy AWS context Boolean settings are not supported.

Editor and visitor search have different users, costs, and quality needs, so the editor choice belongs to the user while the visitor choice belongs to the map. Credential ownership independently controls allowance use.

Public and embedded visitor search accepts anonymous requests. When the map uses a paid provider, these requests consume the map owner’s shared monthly allowance or the installation-wide Enterprise allowance. This monthly pool is the provider-cost and abuse boundary: there is no visitor endpoint per-IP or per-map limiter, and visitor authentication is not required. A local limiter can reject legitimate traffic and does not stop distributed clients. Any public traffic can consume the allowance. Paid search then stops on the affected maps until the monthly reset. To avoid this use of the allowance, disable visitor search or select Free geocoding when it is available. Stronger rate controls require separate platform-wide abuse protection with shared state and a trusted-proxy policy.

Monthly allowances and usage

MapHub tracks three monthly usage pools:

  • OpenCage for OpenCage searches.
  • AWS Stored for editor searches and browser spreadsheet address imports.
  • AWS visitor for visitor searches.

Current allowances are listed on the MapHub pricing page. Business allowances scale with purchased seats. Usage belongs to the map owner and is shared by that owner’s maps.

Account owners can see each pool’s limit, usage, and remaining allowance under Settings → Billing & plans. Usage resets at 00:00 UTC on the first day of each month. When a pool runs out, searches using that pool stop until the allowance resets or the account changes plan.

Credential ownership determines whether usage is limited. MapHub-supplied credentials consume the applicable monthly pool. Customer-supplied AWS credentials are unlimited and produce no usage row. The central allowance resolver derives this from the active request configuration for both consumption and remaining-allowance calculations.

On a hosted installation, usage belongs to the map owner and uses that owner’s plan allowance. On an Enterprise installation, all MapHub-supplied usage shares installation-wide pools configured with the enterprise_geocoding_quota_* site settings. OpenCage currently uses this shared allowance. Usage rows belong to the existing superadmin user with ID 1. One Enterprise deployment represents one customer, so this user is only the accounting subject; Enterprise quota accounting does not require a tenant or account model.

Spreadsheet address imports

Address geocoding is available when a table is uploaded in the map editor. MapHub sends address queries to the external Amazon Location Service using AWS Stored geocoding; this is not an internal MapHub geocoder. It consumes the map owner’s AWS Stored allowance. Rows beyond the geocoding allowance are still imported without locations.

API table imports never geocode addresses and do not consume geocoding allowance. API clients must provide coordinates or inline GeoJSON for located items.

See Importing addresses from a spreadsheet for the browser workflow and XLSX / CSV import for supported columns.