Skip to main content

Pagination

List endpoints support pagination to retrieve large datasets efficiently.

Query Parameters​

  • page (integer, default: 1) - Page number to retrieve
  • limit (integer, default: 10, max: 100) - Number of items per page

Example Request​

curl -X GET "https://api.rivegen.com/api/rivers?page=2&limit=20" \
  -H "Authorization: Bearer <token>"

Response Format​

Paginated responses include a pagination metadata object:

{
  "rivers": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "pages": 8,
    "has_next": true,
    "has_prev": true
  }
}

Fields:

  • page - Current page number
  • limit - Items per page
  • total - Total number of items
  • pages - Total number of pages
  • has_next - Boolean indicating if there's a next page
  • has_prev - Boolean indicating if there's a previous page

Iterating Through Pages​

JavaScript Example:

async function getAllRivers() {
  let page = 1;
  let allRivers = [];
  let hasNext = true;

  while (hasNext) {
    const response = await fetch(
      `https://api.rivegen.com/api/rivers?page=${page}&limit=100`,
      {
        headers: { Authorization: `Bearer ${token}` }
      }
    );
    const data = await response.json();
    allRivers = allRivers.concat(data.rivers);
    hasNext = data.pagination.has_next;
    page++;
  }

  return allRivers;
}

Python Example:

import requests

def get_all_rivers():
    page = 1
    all_rivers = []
    
    while True:
        response = requests.get(
            f"https://api.rivegen.com/api/rivers?page={page}&limit=100",
            headers={"Authorization": f"Bearer {token}"}
        )
        data = response.json()
        all_rivers.extend(data["rivers"])
        
        if not data["pagination"]["has_next"]:
            break
        page += 1
    
    return all_rivers

Best Practices​

  • Use appropriate limit values - larger limits reduce API calls but increase response size
  • Check has_next before making additional requests
  • Respect rate limits when iterating through many pages
  • Consider caching results for frequently accessed data

See Also​