Feature Pagination

Features endpoint

The features endpoint returns one bounded page from the latest published dataset revision. Use it when you want to process features incrementally or restrict the response to a geographic extent.

curl "https://api.mappinest.com/v1/datasets/mappinest.world-cities/features?limit=500&key=YOUR_MAPPINEST_KEY"

Response shape

The response is a GeoJSON FeatureCollection with two additional top-level pagination fields. hasMore reports whether another page exists. nextCursor contains the continuation value or null on the final page.

{
  "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
      }
    }
  ],
  "nextCursor": "eyJ2ZXJzaW9uIjoxLC4uLn0",
  "hasMore": true
}

Follow the cursor

Pass nextCursor back without decoding or changing it. The cursor is bound to the Dataset ID, published revision, and bbox used for the first page. Keep the same bbox on every request in one pagination sequence.

const apiKey = 'YOUR_MAPPINEST_KEY';
const features = [];
let cursor = null;

do {
  const query = new URLSearchParams({
    key: apiKey,
    limit: '1000',
    ...(cursor ? { cursor } : {})
  });

  const response = await fetch(
    'https://api.mappinest.com/v1/datasets/mappinest.world-cities/features?' + query.toString()
  );

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

  const page = await response.json();
  features.push(...page.features);
  cursor = page.nextCursor;
} while (cursor);

console.log(features);

Revision changes

If the dataset is published again before pagination finishes, the previous cursor becomes stale. The API returns 409 with code DATASET_CURSOR_STALE and the current revision. Restart from the first page so one traversal never mixes features from different revisions.

Filter by bounding box

Use bbox to return features whose geometry intersects a WGS84 extent. Longitude values must be between -180 and 180. Latitude values must be between -90 and 90. Minimum longitude and latitude must not be greater than their matching maximum values. Features with null geometry are not included in a bbox-filtered result.

What to read next

• GeoJSON endpoint>
• API Keys & Access>
• Platform Limits>