GeoJSON Endpoint

The GeoJSON endpoint returns the complete latest published dataset revision as one canonical GeoJSON FeatureCollection. Use it when the full dataset fits your application flow and you do not need paginated or spatially filtered reads.

GET

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

Retrieve dataset GeoJSON

curl --compressed "https://api.mappinest.com/v1/datasets/mappinest.world-cities.geojson?key=YOUR_MAPPINEST_KEY"

Load dataset GeoJSON in JavaScript

const apiKey = 'YOUR_MAPPINEST_KEY';

const response = await fetch(
  `https://api.mappinest.com/v1/datasets/mappinest.world-cities.geojson?key=${encodeURIComponent(apiKey)}`
);

if (!response.ok) {
  throw new Error('Dataset GeoJSON request failed.');
}

const dataset = await response.json();
console.log(dataset.features);

Response

GeoJSON response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "city-1",
      "geometry": {
        "type": "Point",
        "coordinates": [12.453387, 41.903282]
      },
      "properties": {
        "name": "Vatican City",
        "featurecla": "Admin-0 capital",
        "pop_max": 832
      }
    }
  ]
}

Response detail	Value
Content type	`application/geo+json`
Document type	GeoJSON `FeatureCollection`
Revision header	`ETag`
Browser cache policy	`private, no-cache`
Compression	Gzip for eligible responses when the client accepts gzip

Conditional reads

Store the returned ETag and send it in If-None-Match on the next request. Mappinest returns 304 Not Modified with an empty body when the authorized dataset revision is unchanged.

Revalidate a dataset revision

curl -i -H 'If-None-Match: "dataset:mappinest.world-cities:r4"' "https://api.mappinest.com/v1/datasets/mappinest.world-cities.geojson?key=YOUR_MAPPINEST_KEY"

Treat the ETag as an opaque revision value copied from the response. Do not construct it from local state in production code.

A newly published revision is served on the next request. There is no cache delay after publishing, so revalidating with the stored ETag is enough to pick it up.

Authorization and CORS

Reads accept the API key in the URL or through X-API-Key. When the key has scopes, include datasets:read. Browser requests must also satisfy the key type and allowed-domain policy configured under API Keys & Access.

An allowed browser origin receives the matching Access-Control-Allow-Origin value and access to ETag, rate-limit, and retry headers. The API does not return a wildcard origin for a restricted key.

Map client guides

The same GeoJSON endpoint can be loaded directly by common web map clients. Each guide includes a standalone JavaScript example and a React component.