API Conventions

Paging

If not for paging, most responses from the Kiva API would be unreasonably large for sending to thousands of requesters every hour. For example, there are over 80,000 loans at Kiva and nearly half a million lenders — each of these data sets are easily several megabytes large. Moreover, most applications can only use or represent a fraction of the data at a time anyway. Paging the data responses helps keep data exchange sane both for Kiva and applications.

We chose a simple model for data paging where page sizes are fixed for any one particular type of data. For example, loan listings currently come 20 to a page; lender listings are offered 50 to a page. Applications should not expect the page size for anyone type of data to stay constant forever, but we also don't plan to change a page size unless we come across a really good reason to do so. Since page sizes are fixed, you only have to supply a page number to pick a cross-section out of a large data response. The default page number for any applicable API method is always 1. For example if you request the list of newest loans suppling no parameters, you'll get paging information in your response that looks something like this (sans comments):

"paging": { "page": 1 // the current page represented "total": 105 // the total number of loan listings for this call "page_size": 20 // the number of listings returned per page "pages": 6 // the total number of pages available }

To get the full list of fundraising loans in this case, you'd need to call the same API method 5 more times with each of the page numbers 2 through 6. Currently, calling the method with page number 7 would return no results.

Kiva
  • © 2009 - 2014 Kiva. All rights reserved.
  • Terms Of Service
  • Kiva is a 501(c)(3) nonprofit.