Pagination

Learn how to efficiently paginate through large result sets.

Overview

The Golfly API uses offset-based pagination. With 17,458 courses in the database, you'll need to paginate to retrieve all results.

Parameter	Type	Default	Max	Description
limit	integer	10	Varies by plan*	Number of results to return
offset	integer	0	—	Number of results to skip

*Max limit by plan: Free=10, Developer=20, Pro=25, Enterprise=50

Response Metadata

Each list response includes a meta object with pagination info:

json

{
  "data": [...],
  "meta": {
    "total": 17458,
    "limit": 10,
    "max_limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Field	Description
total	Total number of matching results
limit	Number of results returned in this response
max_limit	Maximum limit for your plan tier
offset	Number of results skipped
has_more	Whether more results are available

Basic Pagination

bash

# First page (results 1-10 for Free plan)
curl "https://golfly.dev/api/v1/courses?limit=10&offset=0" \
  -H "x-api-key: gf_your_api_key"

# Second page (results 11-20)
curl "https://golfly.dev/api/v1/courses?limit=10&offset=10" \
  -H "x-api-key: gf_your_api_key"

# Third page (results 21-30)
curl "https://golfly.dev/api/v1/courses?limit=10&offset=20" \
  -H "x-api-key: gf_your_api_key"

Fetching All Results

To fetch all courses, loop until has_more is false:

javascript

async function fetchAllCourses(state = null) {
  const courses = [];
  let offset = 0;

  while (true) {
    const params = new URLSearchParams({ offset });
    if (state) params.append('state', state);

    const response = await fetch(
      `https://golfly.dev/api/v1/courses?${params}`,
      { headers: { 'x-api-key': API_KEY } }
    );

    const { data, meta } = await response.json();
    courses.push(...data);

    // Use max_limit from response to know your plan's limit
    console.log(`Fetched ${courses.length} / ${meta.total} (limit: ${meta.max_limit})`);

    if (!meta.has_more) break;
    offset += meta.limit;

    // Small delay to respect rate limits
    await new Promise(r => setTimeout(r, 100));
  }

  return courses;
}

// Usage
const allCourses = await fetchAllCourses();
console.log(`Total: ${allCourses.length} courses`);

Performance Tips

1. Use your plan's maximum limit

The API automatically uses your plan's max limit. Higher tier plans get higher limits, reducing the number of API calls needed.

2. Filter server-side

Use query parameters to reduce result sets. If you only need California courses, add state=California instead of filtering 17k results client-side.

3. Cache results

Golf course data changes infrequently. Cache full result sets for at least 24 hours.

4. Add delays between requests

Add a small delay (100-200ms) between requests to stay well under rate limits.

Requests to Fetch All Courses

Number of requests needed to fetch all 17,458 courses by plan:

Plan	Max Limit	Requests Needed	Monthly Quota
Free	10	1,746	1,000 (not enough)
Developer	20	873	10,000
Pro	25	699	100,000
Enterprise	50	350	1,000,000

Free plan cannot fetch all courses in a single month due to quota limits. Use filters to fetch only what you need.

List Courses API →Rate Limits →