API Endpoints

This page lists all HTTP endpoints exposed by the Data Connector service. Use these endpoints to fetch tiles, search features, manage DataConnectors, and trigger data updates.

Data Retrieval Endpoints

URL Schema

https://dataconnector.maptoolkit.net/{account}/{names}...

Parameter	Description
`account`	Your account name (ex `maptoolkit`)
`names`	Name of the DataConnector (ex `pois`). You can combine the data of multiple DataConnectors with a dash (ex `pois-hotels`)

Authentication

Add your API key as ?api_key=YOUR_API_KEY to every request. See Authentication for details.

TileJSON

GET /{account}/{names}.json

Returns a TileJSON 2.2.0 specification for one or more DataConnectors.

Parameter	Type	Required	Description
`filter`	string	No	JSON filter expression to restrict which features are included.
`ids`	string	No	JSON array of feature IDs to restrict results to specific features.
`query`	string	No	Text query string passed to the backend for filtering.
`optimize`	string	No	Style-based tile optimization in the format `styleid,source,prop1,...`.
`rerender`	string	No	When set, bypasses the tile cache and forces a fresh render.

Vector Tiles

GET /{account}/{names}/{z}/{x}/{y}.{pbf|png|webp|jpeg}

Returns a tile for the given zoom level and coordinates. Use pbf for vector tiles (Protocol Buffer format), or an image format for raster tiles. Combine multiple DataConnectors with a dash. Maximum zoom level is 20 for raster tiles and 18 for vector tiles.

Parameter	Type	Required	Description
`filter`	string	No	JSON filter expression to restrict which features are included.
`ids`	string	No	JSON array of feature IDs to restrict results to specific features.
`query`	string	No	Text query string passed to the backend for filtering.
`optimize`	string	No	Style-based tile optimization in the format `styleid,source,prop1,...`; strips unused properties to reduce tile size.
`rerender`	string	No	When set, bypasses the tile cache and forces a fresh render.

Feature Export

GET /{account}/{name}/{id}.{geojson|kml|gpx}

Exports a single feature by ID as GeoJSON, KML (Keyhole Markup Language), or GPX (GPS Exchange Format). KML and GPX are only available for LineString geometries. For GeoJSON, you can export multiple features by passing a comma-separated list of IDs.

Query Cache

POST /{account}/{name}/querycache
GET  /{account}/{names}/querycache

Use POST to create a cached result set for a query. Use GET to retrieve the total count, bounding box, and optionally the IDs of matching features across one or more DataConnectors.

POST body parameters:

Parameter	Type	Required	Description
`filter`	string	No	JSON filter expression to restrict which features are cached.
`ids`	string	No	JSON array of feature IDs to restrict the cached result.
`query`	string	No	Text query string passed to the backend for filtering.

GET query parameters:

Parameter	Type	Required	Description
`filter`	string	No	JSON filter expression to restrict which features are included.
`ids`	string	No	JSON array of IDs to filter by; also includes matched IDs in the response when set.
`query`	string	No	Text query string passed to the backend for filtering.
`remoteids`	string	No	When set, includes the original source IDs from the backend in the response.

Search

GET /{account}/{name}/search

Searches the DataConnector and returns a GeoJSON FeatureCollection with matching features.

Parameter	Type	Required	Description
`query`	string	No	The search text to match against indexed fields.
`filter`	string	No	JSON filter expression to restrict which features are searched.
`ids`	string	No	JSON array of feature IDs to restrict the search to specific features.
`limit`	integer	No	Maximum number of features to return (max 1000). Default: `100`.
`offset`	integer	No	Number of features to skip, for pagination. Default: `0`.

Map Preview

GET /{account}/{name}.html

Returns an HTML map preview of the DataConnector using the Maptoolkit JS library.

Parameter	Type	Required	Description
`iframe`	boolean	No	When set to `true`, wraps the map in an `<iframe>` element.

REST API

All REST API endpoints require write permission and account ownership. Authenticate using your API key.

List DataConnectors

GET /api/{account}

Returns all DataConnectors for the account as a JSON array, sorted by last update time. Each entry includes the full configuration and any current fetch or insert errors.

curl https://dataconnector.maptoolkit.net/api/maptoolkit?api_key=YOUR_API_KEY

Create or Update DataConnector

POST /api/{account}

Creates a new DataConnector or updates an existing one. After saving, triggers a full data fetch automatically. Returns the saved resource object.

The name field must be unique within the account and may only contain lowercase letters, digits, and underscores (a-z, 0-9, _).

See Data Sources for detailed information on configuring the different data sources.

Field	Type	Required	Description
`name`	string	Yes	Unique name for the DataConnector.
`backend`	string	Yes	Backend type (e.g., `postgres`, `solr`, `geojson`). See Data Sources.
`data_endpoint`	object	Yes	Backend-specific connection and query configuration.
`permissions`	object	No	Access control. Default: `{}` (private).
`tags`	array	No	Tags for grouping DataConnectors. Default: `[]`.
`tilejson`	object	No	TileJSON overrides (e.g., `minzoom`, `maxzoom`, `center`).
`update_endpoint`	object	No	Endpoint config for query-based partial updates.
`search_endpoint`	object	No	Endpoint config for backend-side search.
`reload_interval`	string	No	Auto-reload interval in hours (e.g., `"24"`).
`id_field`	string	No	Field to use as the feature ID.
`title_field`	string	No	Field to use as the display title.
`geometry_field`	string	No	Field containing the geometry.
`geometry_format`	string	No	Geometry format (e.g., `geojson`, `wkt`).
`data_fields`	array	No	Fields to store and index.
`vectortile_fields`	array	No	Fields to include in vector tiles.
`trie_fields`	array	No	Fields to index for prefix search.
`order_field`	string	No	Field to sort results by.
`order_direction`	string	No	Sort direction (`asc` or `desc`).
`grid_size`	number	No	Grid cell size for cluster aggregation.
`grid_threshold`	number	No	Feature count above which clustering activates.
`field_rename`	object	No	Map of source field names to renamed output fields.

curl -X POST https://dataconnector.maptoolkit.net/api/maptoolkit?api_key=YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pois",
    "backend": "postgres",
    "data_endpoint": {
      "host": "localhost",
      "port": 5432,
      "database": "mydb",
      "user": "myuser",
      "password": "mypassword",
      "query": "SELECT id, name, ST_AsGeoJSON(geom) as geometry FROM pois"
    },
    "id_field": "id",
    "geometry_field": "geometry",
    "vectortile_fields": ["name"]
  }'

See Data Sources for detailed information on configuring the different data sources.

Get DataConnector Configuration

GET /api/{account}/{name}

Returns the full configuration and metadata for a single DataConnector.

curl https://dataconnector.maptoolkit.net/api/maptoolkit/pois?api_key=YOUR_API_KEY

Export All Items

GET /api/{account}/{name}/items.{ndjson|geojson}

Streams all items stored in the DataConnector. Use ndjson to get one JSON object per line, or geojson to get a full GeoJSON FeatureCollection. Closes the connection cleanly if you disconnect before the stream ends.

curl https://dataconnector.maptoolkit.net/api/maptoolkit/pois/items.geojson?api_key=YOUR_API_KEY

Trigger Data Update

POST /api/{account}/{name}

Triggers a data update. There are three modes depending on what you send in the request body:

Full re-fetch — Send an empty body. The DataConnector re-fetches all data from its configured data_endpoint, then clears the query cache and tile cache. Use this after your source data has changed.

curl -X POST https://dataconnector.maptoolkit.net/api/maptoolkit/pois?api_key=YOUR_API_KEY

Query-based partial update — Send a JSON body with a query field. The DataConnector fetches matching items from the configured update_endpoint using that query, and updates only those items. Requires update_endpoint to be configured on the DataConnector.

curl -X POST https://dataconnector.maptoolkit.net/api/maptoolkit/pois?api_key=YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{"query": "id:123"}'

Push data — Send a JSON body with feature data and no query field. The DataConnector parses the body using the backend’s own format and updates the matching items. Not supported by all backends — returns HTTP 501 if the backend does not support push. For Solr, the body must match the Solr response format ({ "response": { "docs": [...] } }).

curl -X POST https://dataconnector.maptoolkit.net/api/maptoolkit/pois?api_key=YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{"response": {"docs": [{"id": "123", "name": "My POI"}]}}'

Delete DataConnector

DELETE /api/{account}/{name}

Deletes the DataConnector and all its data. If the DataConnector uses the tag backend, also removes the tag reference from all associated DataConnectors. Returns "OK" on success.

curl -X DELETE https://dataconnector.maptoolkit.net/api/maptoolkit/pois?api_key=YOUR_API_KEY

Delete a Specific Item

DELETE /api/{account}/{name}/{id}

Deletes a single item by ID from the DataConnector and invalidates the affected tile and query cache. Returns "OK" on success.

curl -X DELETE https://dataconnector.maptoolkit.net/api/maptoolkit/pois/123?api_key=YOUR_API_KEY

Connector Documentation