Pagination

When working with large datasets, it's crucial to implement pagination to manage the amount of data returned in each API request. This guide will walk you through how pagination works in the Roozna API and how to use it effectively.

How pagination works

Roozna uses cursor-based pagination for its API endpoints that return lists of items. This method is more efficient and consistent than offset-based pagination, especially for large datasets.

Pagination parameters

Name
limit
Type
integer
Description
The number of results to return per page (default: 20, max: 100).
Name
cursor
Type
string
Description
A pointer to a specific item in the dataset. Used to determine where to start fetching the next set of results.

Paginated response structure

When you make a request to an endpoint that supports pagination, the response will include a results array containing the requested data, as well as a pagination object with metadata about the current page and links to fetch more results.

Pagination object

Name
total
Type
integer
Description
The total number of items available.
Name
limit
Type
integer
Description
The number of items returned in this response.
Name
next_cursor
Type
string
Description
The cursor to use for the next page of results. Will be null if there are no more results.
Name
previous_cursor
Type
string
Description
The cursor to use for the previous page of results. Will be null for the first page.

Response

{
  "results": [
    {
      "id": "b1234567-89ab-cdef-0123-456789abcdef",
      "name": "TechNova Solutions",
      // ... other business properties
    },
    // ... more businesses
  ],
  "pagination": {
    "total": 1000,
    "limit": 20,
    "next_cursor": "YXJyYXljb25uZWN0aW9uOjE5",
    "previous_cursor": null
  }
}

Using pagination

Here's how to use pagination when searching for businesses:

Initial request

For your first request, you typically don't need to provide a cursor. Just set the limit if you want a different number of results than the default.

Subsequent requests

To fetch the next page of results, include the next_cursor from the previous response in your new request.

Handling the last page

When you've reached the last page of results, the next_cursor in the response will be null. This indicates that there are no more results to fetch.

Request

GET

/v1/search

# Initial request
curl -G https://api.roozna.com/v1/search \
  -H "X-API-Key: {your_api_key}" \
  -d q="tech startups" \
  -d limit=20

# Subsequent request
curl -G https://api.roozna.com/v1/search \
  -H "X-API-Key: {your_api_key}" \
  -d q="tech startups" \
  -d limit=20 \
  -d cursor=YXJyYXljb25uZWN0aW9uOjE5

Best practices

When implementing pagination in your application, consider these best practices:

Use appropriate page sizes: Choose a limit that balances between reducing the number of API calls and not overwhelming your application with too much data at once.
Handle rate limits: Be mindful of your API rate limits when making multiple paginated requests in quick succession.
Implement infinite scrolling: For a smooth user experience, consider implementing infinite scrolling in your frontend, fetching the next page of results as the user scrolls.
Cache results: If appropriate for your use case, consider caching paginated results to reduce API calls and improve performance.
Handle errors gracefully: Ensure your application can handle scenarios where the API might return an error or an unexpected response format.

Conclusion

Proper use of pagination is crucial for efficiently working with large datasets in the Roozna API. By following this guide and implementing the best practices, you can create applications that handle large volumes of business data smoothly and efficiently.

Explore the Search API documentation