Pagination

List endpoints return results in pages so applications can process large result sets efficiently.

The API uses cursor-based pagination. Clients should use the cursor returned by the current response to request the next page.

Default and maximum limit

If limit is omitted, the API returns up to 20 records:

GET /v1/clubs

This is equivalent to:

GET /v1/clubs?limit=20

The maximum page size is 100:

GET /v1/clubs?limit=100

Requests exceeding the maximum limit are rejected with 400 Bad Request.

Request the first page

Use limit to specify the maximum number of records returned:

curl 'https://api.eae.golf/v1/clubs?limit=20' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json'

The response contains the records and pagination information:

{
  "data": [
    {
      "slug": "green-eagle-golf-courses",
      "name": "Green Eagle Golf Courses"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "NEXT_CURSOR_VALUE"
  },
  "meta": {
    "apiVersion": "v1"
  }
}

Request the next page

When hasMore is true, pass nextCursor as the cursor parameter:

curl 'https://api.eae.golf/v1/clubs?limit=20&cursor=NEXT_CURSOR_VALUE' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json'

Continue until the response contains:

{
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

Preserve the original filters

Include the same filters when requesting subsequent pages.

For example, the first request might be:

curl 'https://api.eae.golf/v1/clubs?lat=53.5511&lon=9.9937&radius_km=100&public=true&limit=20' \
  --header 'Authorization: Bearer YOUR_API_KEY'

The next request should preserve those parameters:

curl 'https://api.eae.golf/v1/clubs?lat=53.5511&lon=9.9937&radius_km=100&public=true&limit=20&cursor=NEXT_CURSOR_VALUE' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Changing the filters, location, radius or ordering while reusing a cursor can produce invalid or inconsistent results. Start a new pagination sequence whenever the query changes.

Treat cursors as opaque values

Do not decode, modify or construct cursors in the client.

A cursor represents the position of the next page according to the API’s ordering rules. Its internal format may change without notice while its public behaviour remains stable.

Store and transmit the value exactly as returned:

const nextCursor = response.pagination.nextCursor;

When constructing URLs programmatically, encode it as a query parameter:

const parameters = new URLSearchParams({
  limit: '20',
  cursor: nextCursor
});

Process pages sequentially

A cursor for the next page is only available after the current page has been returned. Cursor-based pages should therefore be requested sequentially.

let cursor = null;
let hasMore = true;

while (hasMore) {
  const parameters = new URLSearchParams({
    limit: '20'
  });

  if (cursor) {
    parameters.set('cursor', cursor);
  }

  const response = await fetch(
    `https://api.eae.golf/v1/clubs?${parameters}`,
    {
      headers: {
        Authorization: `Bearer ${apiKey}`,
        Accept: 'application/json'
      }
    }
  );

  if (!response.ok) {
    throw new Error(`API request failed with status ${response.status}`);
  }

  const result = await response.json();

  for (const club of result.data) {
    processClub(club);
  }

  hasMore = result.pagination.hasMore;
  cursor = result.pagination.nextCursor;
}

Choose an appropriate limit

Smaller pages:

• Return more quickly
• Use less memory
• Are suitable for interactive interfaces

Larger pages:

• Require fewer requests
• Are useful for background processing
• Transfer more data per request

Use the smallest page size that suits the application. The API may enforce a maximum limit; consult the relevant endpoint definition in the API reference.

Data changes during pagination

Club records may be updated while an application is processing multiple pages. Cursor pagination provides more stable behaviour than offset-based pagination, but clients performing long-running synchronizations should still be prepared to handle updated or repeated records.

Use the club slug or id as the stable identifier when storing results locally.