When you fetch loans, they are returned in one of two ways – a loan listing or a loan detail view. Loan listings are returned from API calls where the results can be numerous and span many pages of data. If you fetch the loans associated with a lender, you'll get loan listings. Each listing has enough information for showing a summary of the key details on the loan, such as the name, the photo, the loan amount, and the planned use of the loan. The simplest way to get a listing of loans is call the
loans/newest method without any parameters:
This returns listings for up to 20 of the newest loans at Kiva that are currently raising funds. Here's what one loan listing looks like in JSON:
Here we can see that Le Thi Tan of Quang Xuong, Viet Nam is requesting an individual loan to buy more ducks and chickens for a poultry business. We can also show that $125 of the $550 needed has already been funded. The loan description is available in two languages, Vietnamese and English, and the loan was posted on January 9, 2008 at 1:50am PST.
A couple of details are not obvious from this view, namely, the image and the details on the field partner. Requesting Kiva images is a relatively simple process that we'll cover in a later section. Requesting partner information is also pretty simple and is something we expect most applications to do infrequently but regularly.
Though there are tens of thousands of loans on Kiva, there are currently less than hundred active partners. For this reason, we've designed the API so you can fetch the list of partners and cache it for reuse over lots of different calls. This way, we don't have to send you redundant information about partners every time you call the API. For now, the list of partners is available in a single page of data at:
Each partner is indexed with a partner ID which is easy to match up with the
partner_id field from a loan listing. For instance, the loan from Viet Nam in the earlier example has the partner ID
67 which matches up with the partner, TYM Fund. The partner started posted loans at Kiva in June 2007 and, at the time of writing, has a 4 star rating. When rendering the loan it would make sense to show some of this information about the partner as well.
Flipping things on their head, you can also start with a partner ID (presumably fetched from the partner API method) and then fetch the list of all loans offered by the partner. For this we use the
This call returns a list of all loans from one of our most active partners, Microfinanzas PRISMA. This call begins to show capability of one of the most useful and powerful methods in the API, loan search. For instance, let's say we wanted to get a listing of all the loans from partners in Uganda which are currently fundraising. To do this, we would again use the
partners method in conjunction with the
loans/search call. First, we look through the data returned by the partner call to find all partners operating in Uganda. Then we plug those in as an array of IDs along with a value for the
status parameter to the loan search:
The status of a loan is an especially important concept to understand when working with loans. Here is the list of loan statuses and what each means:
funded_dateshows the exact time at which the loan was fully funded on Kiva.
in_repaymentstatus. When a loan remains delinquent 6 months after the end of the loan payment schedule, the loan becomes defaulted. Usually defaulted loans will never be paid back and are a financial loss to the lenders to that loan. Most loans only default in part, but it is possible for the entire amount of the loan to not be repaid.
You may have noticed that the terms used in the Kiva API for loan status do not always match up with the terminology used on the site. We feel the terms used in the API are clear and acceptable for communicating to lenders, though you are free to choose the terminology we currently use on the website as well.
As we've seen so far, there are lots of ways to fetch listings of loans. Loan details, on the other hand, are only available by explicit request once you have the ID for a loan but they include all the specifics about a loan that you want to represent in your application. This includes the loan description, the loan schedule (in both US dollars and the local currency), any payments made to the loan so far, the list of borrowers on the loan, and the number and type of journal entries the loan has.
The best way to get familiar with this view is to make a request in JSON or in XML and take a look at the data yourself. However, we do want to go over some of the detailed terminology associated with a loan. It can get a bit complex even if you happen to have a background in finance.
nonpayment, the party liable can either be the
currency_exchangethe liability can be
shared, fully resting on the
noneif the currency is locked to the US dollar. If currency exchange loss is a shared liability, the
currency_exchange_coverage_ratewill also be listed. (For more information on these topics, search for "default protection" or "currency exchange" at our Help Center.)
Also, there are a couple items which only apply to loans in fundraising status:
loan_amountthe loan moves to a funded state (soon followed by
funded_amount + basket_amount >= loan_amountyou may consider the loan as unavailable through it is still in the state of raising funds. (NOTE: The Kiva website currently renders the "amount raised" for a loan as
funded_amount + basket_amountand filters out loans which have no amount currently available for purchase. Choose the way you best see fit to handle this in your own application.)
Since the Kiva API currently does not let you facilitate loan transactions, it is likely that you will want to link a loan from your application to a page at Kiva.org where a user can lend to an entrepreneur. For now, we suggest linking loans to the entrepreneur's page using this URL pattern:
<id> is the ID of the loan you want to link.