Dataset API | Mappinest Docs

Overview

The Dataset API stores editable vector features and delivers the latest published dataset revision as GeoJSON through authenticated endpoints. You can upload GeoJSON, start with a blank dataset, edit features in Dataset Studio, and consume the result from a browser, desktop app, or back-end service.

Use the Dataset API when your application needs feature-level GeoJSON that can change over time. Use the Tiles API for uploaded MBTiles or PMTiles tilesets that are already prepared for vector or raster tile delivery. Use the Maps API for available map styles loaded through StyleJSON.

Dataset workflow

Open Datasets and select Add Dataset.
Upload a .geojson or .json file, or select Start drawing to create a blank dataset.
Review and edit points, lines, polygons, and feature properties in Dataset Studio.
Select Publish to create the next immutable dataset revision.
Read the published revision through the full GeoJSON, metadata, or paginated feature endpoint.

Choose an endpoint

Endpoint	Use it for
`GET /v1/datasets/{datasetId}.geojson`	Download or load the complete published FeatureCollection.
`GET /v1/datasets/{datasetId}/features`	Read bounded pages with an optional `bbox` filter.
`GET /v1/datasets/{datasetId}`	Read dataset metadata, bounds, size, feature count, and revision.

Dataset ID

Every dataset has an owner-scoped ID in the form account.slug. Read examples use `mappinest.world-cities`. Copy the exact Dataset ID from the Datasets page or the dataset details panel when working with your own data. Dataset IDs used by the public API are lowercase.

Dataset metadata

Use the metadata endpoint to inspect the current published revision without transferring the complete FeatureCollection.

GET

https://api.mappinest.com/v1/datasets/{datasetId}?key=YOUR_KEY

Field	Description
`id`	Owner-scoped Dataset ID.
`name` / `description`	Current published display metadata.
`status`	Current state such as `empty`, `importing`, `ready`, or `failed`.
`featureCount`	Number of features in the published revision.
`sizeBytes`	Canonical uncompressed GeoJSON size in bytes.
`bounds`	WGS84 extent in `[minLng, minLat, maxLng, maxLat]` order, or `null` when no bounds are available.
`revision`	Current published revision number.
`createdAt` / `updatedAt`	ISO 8601 timestamps for the dataset.

Authentication

Dataset reads accept an API key through the key query parameter or the X-API-Key request header. Configure datasets:read when you create a scoped key. Domain restrictions work for browser reads and must include every allowed application origin.

Owner access

An API key can access datasets owned by the same Mappinest account. Dataset API keys do not provide a separate per-dataset allowlist.

Revisions and caching

Every successful Publish advances the dataset revision and returns a new ETag. Read requests can send If-None-Match and receive 304 Not Modified when the published revision has not changed.

The full GeoJSON endpoint authorizes every request and can reuse the immutable revision from the Mappinest edge cache. The public response remains private, no-cache, so browsers revalidate access and revision state instead of treating the response as public shared content. Metadata and feature-page responses are not stored in the revision cache.

Rate limits

Dataset reads use a rolling limit for each viewer IP. Visitors can therefore use the same public read key without sharing one rolling read budget.

Read the live budget from the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset response headers. After an HTTP 429 response, wait for the duration provided by Retry-After before retrying.

Dataset API pricing

Free includes up to 100,000 dataset requests per month.
Flex includes up to 1M dataset requests per month.
Current allowances and overage rates are listed on the pricing page.

Successful 2xx responses and authorized 304 Not Modified responses count as dataset requests. A 304 response records zero response bytes. HEAD responses also record zero response bytes. Failed requests and CORS preflight requests are not included in Dataset API usage.