Overview
Connect and configure external services in Parchment through the Settings UI.
Parchment connects to external services — maps, search engines, geocoders, routing engines, and more — through a unified integrations system. All integrations are configured through the UI rather than environment variables, making it easy to swap providers or adjust capabilities without restarting the server.
Managing integrations
Go to Settings → Integrations to see all available integrations. Each card shows:
- The integration's name and description
- Which capabilities it is currently fulfilling (shown as blue badges when active)
- Action buttons to edit settings or remove the integration
Configuring an integration
Click the settings icon on any integration card to open the edit dialog. Every integration has the following fields:
| Field | Description |
|---|---|
| Host | Base URL of the service (e.g. http://localhost:3002). Required for self-hosted services. |
| API Key | Bearer token or API key used to authenticate requests. Leave blank if the service is open. |
| Enabled | Toggle to activate or deactivate the integration without removing it. |
| Capabilities | Per-feature toggles that control which Parchment features this integration handles. |
Test Connection
Before saving, click Test Connection to verify that Parchment can reach the service with the credentials provided. You must pass this check to save the configuration.
Capabilities
Capabilities map Parchment features to integration providers. Multiple integrations can be configured for the same capability — Parchment will try them in priority order and fall back gracefully if one is unavailable.
| Capability | Description |
|---|---|
| Search | Text and semantic place search |
| Autocomplete | Low-latency typeahead suggestions |
| Search Category | Browsing places by OSM category |
| Place Info | Fetching full place detail by ID |
| Geocoding | Address-to-coordinate lookup |
| Routing | Turn-by-turn directions |
| Map Engine | Base map tile rendering |
| Map Layer | Overlay tile layers |
| Transit Data | Public transit routes and stops |
| Street View | Street-level imagery |
| Spatial Contains | Find which areas contain a coordinate |
| Spatial Children | List POIs inside a venue or area |
| Weather | Current conditions and forecasts |
| Edit Map | Create OSM notes, comment on notes, and submit map edits |
| Logging | Telemetry and observability export |
Not all integrations support every capability — the edit dialog only shows toggles for capabilities the integration actually provides.
Degraded mode
If a capability has no active integration (or all configured integrations fail their health checks), Parchment degrades gracefully:
- Search falls back to remaining active search providers
- Map tiles fall back to the next configured map engine
- Features with no provider available are hidden from the UI rather than surfacing errors
Available integrations
Parchment has two types of integrations:
- System integrations are configured once by an admin and apply to the entire instance. These provide backend capabilities like map rendering, search, and geocoding.
- User integrations are connected individually by each user. These grant Parchment permission to act on the user's behalf with an external service.
System integrations
| Integration | Capabilities |
|---|---|
| Barrelman | Search, Autocomplete, Search Category, Place Info, Spatial Contains, Spatial Children |
| Mapbox | Map Engine |
| Google Maps | Search, Place Info, Geocoding |
| Pelias | Geocoding, Autocomplete |
| Nominatim | Search, Geocoding, Place Info |
| GraphHopper | Routing |
| Valhalla | Routing |
| Geoapify | Search Category, Autocomplete, Geocoding, Place Info, Routing |
| Mapillary | Map Layer, Street View |
| Transitland | Map Layer, Transit Data, Place Info |
| Overpass | Search Category, Place Info |
| Wikidata | Place Info |
| OpenWeatherMap | Weather |
| Axiom | Logging |
| OpenStreetMap | (configuration only — stores OAuth credentials for user authentication) |
User integrations
Some integrations require a corresponding system integration to be configured first. For example, users can only connect their OpenStreetMap account after an admin has set up the OpenStreetMap system integration with OAuth credentials.
| Integration | Capabilities | Requires |
|---|---|---|
| OpenStreetMap Account | Edit Map | OpenStreetMap (system) |