Connector Documentation

A data source defines where a Connector reads its data from. You configure it by choosing a backend and setting the matching options. This page describes each available backend, what kind of data it connects, and how you set it up. Headings match the names shown in the Connector creation wizard.

Backends set up data in one of three ways:

• Upload: You upload a file in the wizard. Maptoolkit stores the data. Nothing outside Maptoolkit is involved.
• Connection: You configure a connection with parameters, such as a URL, a database host, or an access token. The Connector reads the data from your system and refreshes it when it reloads.
• Code or grouping: You write code, or you combine Connectors that already exist.

Airtable

Use this backend for data you maintain in an Airtable base, such as a list of places, offers, or events. Each record in the table becomes one item. Airtable has no geometry field type, so store the location in a field and select it as the geometry field of the Connector (for example as latlng or GeoJSON).

You set this up as a connection. You enter the base ID, the table name, and a Personal Access Token. The data stays in Airtable, and the Connector reads it again on every reload. Linked records and multi-select fields become comma-separated values, and attachments are stored as JSON.

• Supports reading from a specific view instead of the default view
• Forwards additional query parameters, such as filterByFormula, to Airtable
• Paginates through all records in batches of 100 when enabled

Apache Solr

Use this backend when your geodata is in an Apache Solr search index, for example the index behind the search of your website. Each Solr document becomes one item, and the document needs a field that contains the location. Multi-value fields are stored as comma-separated values, and nested objects are stored as JSON strings.

You set this up as a connection. You enter the URL of the Solr select handler and the query parameters to use. You do not upload anything. The Connector copies the matching documents and reads them again on every reload. If the server needs basic authentication, put the credentials in the URL.

• Paginates through large result sets in batches of 1,000 when paged is enabled. Without it, the Connector reads at most the first 1,000 documents.
• Forwards query parameters to Solr

Custom JavaScript

Use this backend when no built-in backend fits your data source, for example an API with its own login flow or a format the other backends cannot read. You write JavaScript code that fetches the data and returns it as GeoJSON features. The code runs in a sandbox on the Maptoolkit side.

You do not upload data and you do not configure a connection with parameters. You write the code, and the code decides where the data comes from. The Connector runs the code on every reload.

• Full control over fetch logic and data shape
• Output must be a stream of NDJSON (Newline Delimited JSON) features

Elasticsearch

Use this backend when your geodata is in an Elasticsearch index. Each document becomes one item. Nested fields are flattened and their names are joined with _, so store.location.name becomes store_location_name. The document needs a field that contains the location, for example a GeoJSON geometry.

You set this up as a connection. You enter the URL of the _search endpoint and the query body to use, and you can add HTTP headers. You do not upload anything. The Connector copies the matching documents and reads them again on every reload.

• Same URL is used both for the periodic full fetch and for on-demand search queries
• Supports custom HTTP headers, for example to set Referer on clusters that check it
• Paginates using from/size, added automatically to the query body when enabled

File Upload

Use this backend for data that you have as a file and that does not change often. You can upload GeoJSON, GeoPackage, GPX, KML/KMZ, CSV, Excel, or a zipped Shapefile. The Connector converts every file to GeoJSON. For files with several layers, such as GPX waypoints, routes, and tracks, it merges all non-empty layers into one data set. For CSV and Excel, each row needs a geometry column (GeoJSON) or a latitude and longitude column pair. For CSV, a WKT column also works.

You set this up as an upload, not as a connection. You upload the file in the Connector creation wizard, and Maptoolkit stores it. No external server is involved. The data does not change until you upload a new file and select it as the active file.

• Accepts GeoJSON, GeoPackage, GPX, KML/KMZ, CSV, Excel, or a zipped Shapefile (.shp, .shx, .dbf, and .prj must be included)
• Converts the uploaded file to GeoJSON on upload and streams it to handle large files without loading everything into memory
• You can store multiple files, but only one is active as the data source at a time

GeoJSON over HTTP

Use this backend when a URL serves your data as a GeoJSON FeatureCollection. The URL can point to a static file, such as an export on your web server or an open-data portal, or to an API that creates the GeoJSON on request. Each feature becomes one item. The properties of a feature become fields, and nested objects are stored as JSON strings.

You set this up as a connection, not as an upload. You enter the URL and, if needed, extra query parameters. The Connector fetches the URL on every reload, so changes on your server show up after the next reload. If the server needs basic authentication, put the credentials in the URL. To upload a GeoJSON file to Maptoolkit instead, use File Upload.

• Pages through results with limit and offset (1,000 features per page) when paged is enabled
• Stores the feature id as id

Google BigQuery

Use this backend for geodata in Google BigQuery. You write a SQL query, and the rows of the result become the items. BigQuery’s GEOGRAPHY type is always WGS84, so you can export a geometry column as GeoJSON in the query.

You set this up as a connection. You enter the project ID, the query, and the key of a service account. The data stays in BigQuery, and the Connector runs the query again on every reload.

• Requires a service account key with the BigQuery Data Viewer and BigQuery Job User roles
• Set the dataset location only if it is outside the US or EU multi-region (for example europe-west1)
• Use ST_ASGEOJSON(geom) AS geometry to export the geometry column as GeoJSON - BigQuery’s GEOGRAPHY type is always WGS84
• An optional search query supports ? placeholders for parameters passed via the query HTTP parameter

imx.Platform GraphQL

Use this backend for tourism content in imx.Platform: tours, events, and points of interest (POIs). The Connector reads the content through the GraphQL Content Delivery API of imx.Platform. It extracts the geometry from the nested GraphQL response: tours become lines, events and POIs become points. Nested address and location fields are flattened.

You set this up as a connection. You enter the URL of the GraphQL endpoint, a bearer token, the operation name, and the GraphQL query. The content stays in imx.Platform, and the Connector reads it again on every reload.

• Bearer token authentication
• Paginates automatically at 1000 items per page
• Extracts geometry for tours (LineString), events (Point), and POIs
• Flattens nested address and location fields

PMTiles over HTTP

Use this backend when you already have vector tiles in a PMTiles archive - a single-file tile format served over HTTP. The tiles are already finished, so the Connector does not read, store, or index any features. Filters and search queries do not work with this backend.

You set this up as a connection. You enter the URL of the archive, and the server behind it must support HTTP range requests. You do not upload the archive to Maptoolkit. The Connector reads tiles on demand from your URL.

PostgreSQL

Use this backend for geodata in a PostgreSQL database, usually with PostGIS. You write a SQL query, and the rows of the result become the items. This lets you use joins and expressions to prepare the data. Export the geometry column as GeoJSON in the query, for example with ST_AsGeoJSON.

You set this up as a connection. You enter the host, port, database, user, password, and the query. The database must be reachable from Maptoolkit’s servers. The data stays in your database, and the Connector runs the query again on every reload.

• Supports any SQL query, including joins and expressions
• Streams results to handle large datasets without loading everything into memory

Supabase

Use this backend for data in a Supabase project. The Connector reads rows from a table or view through the REST API that Supabase generates (PostgREST). Each row becomes one item. Array columns become comma-separated values, and json and jsonb columns are stored as JSON strings.

You set this up as a connection. You enter the project URL, the table name, and an API key. The data stays in Supabase, and the Connector reads it again on every reload.

• The table or view must be exposed in the public schema via Project Settings → Data API
• Use the anon key for data subject to Row Level Security, or service_role to bypass it - treat service_role like a database password
• Forwards a raw PostgREST query string to filter or select columns, for example select=id,name,geometry&status=eq.active
• If no geometry column is exposed as GeoJSON, expose a view with ST_AsGeoJSON(geom) AS geometry
• Paginates through all rows in batches of 1,000 using limit/offset when enabled

Vector Tile Server

Use this backend when you already run a vector tile server and want to cache its output. The Connector passes each tile request on to your server and stores the response, so repeated requests do not reach your server. The tiles are already finished, so the Connector does not read, store, or index any features. Filters and search queries do not work with this backend.

You set this up as a connection. You enter the tile URL template with the {z}, {x}, and {y} placeholders. You do not upload anything. Tiles are requested on demand, or in advance if you set a bounding box and zoom range for seeding.

• Supports standard {z}/{x}/{y} tile URL templates
• Can pre-seed tiles for a specific bounding box and zoom range

Grouped Data Source (Tags)

Use this backend to combine the data of several Connectors into one Connector, so your app needs only one endpoint. It does not read any external data itself. The data comes from the Connectors that share the tag. This is not a backend you pick from the Backend selection in step 1 - it is created automatically when a Connector uses the optional Tags field during creation, and a matching Tag backend does not already exist for that tag.

You set up nothing for the grouped data source itself: no upload and no connection. You only add the same tag to the Connectors you want to group.

• Merges field definitions (data_fields, vectortile_fields, trie_fields) from all tagged sources
• Prefixes item IDs with the source Connector name to avoid collisions (e.g., pois_123)
• Rebuilds automatically when any tagged Connector is updated