Fetching Data

Lenders

Like loans, lenders have two forms of representation, that suitable for listing and a more detailed view. Lender listings are fairly simple and will include a name, a lender ID, and possibly locational information. Here's an example of the lender listing for one of Kiva's first engineers, Jeremy:

{ "lender_id": "jeremy", "name": "SmooveJ", "whereabouts": "San Francisco CA", "country_code": "US", "image": { "id": 172368, "template_id": 1 } }

This is enough information to show a picture of Jeremy with his name as well as where he is from.

As an example of lender listings, you can request a list of lenders associated with a particular loan:

http://api.kivaws.org/v1/loans/38239/lenders.json

Since there may be many lenders to a loan it is possible you have to span a few pages of data to fetch all a loan's lenders. However, by giving you up to 50 lenders per page of data we hope this case is rare.

Lender IDs and Lender Pages

You may have noticed that lenders are not referenced by numerical IDs but by alphanumeric identifiers. By default, lender IDs are automatically issued when a lender signs up for Kiva and creates a public profile. However, a lender can change his ID (as well as most other details as well) so you should never expect that this identifier will always stay the same for a lender, much less, valid as an identifier on Kiva. However, it is true that most lenders rarely change their lender ID since changing this also modifies the URL for their lender page.

If you want to provide a link in your application to a lender's Lender Page on the Kiva website, all you need is the lender_id and this URL template:

http://www.kiva.org/lender/<lender_id>

So, as an example, Jeremy's lender page is available at:

http://www.kiva.org/lender/jeremy

What if a lender doesn't know his Lender ID? We've added a handy page to the Kiva website to help lenders figure this out. Direct users this URL and they will be shown their lender ID after successful login to Kiva:

http://www.kiva.org/myLenderId

Lender Detail

A lender has much less information available than a loan. However, as you'll notice on Lender Pages, there is more information than we provide in lender listings. In addition to the common fields at the top of the lender page you'll also find a count for the number of loans and invites he has made. This is handy to check before deciding whether or not to fetch the list of loans for a lender.

The best way to get familar with the lender detail view is to make a request like this one and inspect the results:

http://api.kivaws.org/v1/lenders/matt.xml

Loans for a Lender

It's probably pretty obvious by now but fetching the list of loans is not much different that any other loan-listing API method. To see the 20 most recent loans Matt, Kiva's CEO, has made, you would use this call:

http://api.kivaws.org/v1/lenders/matt/loans.json

As you would expect, the format of the results looks like that of loans/newest or loans/search.

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