Fetching Data

Loans

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.

Field Partner Information

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 loans/search method.

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:

Loan Status

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:

fundraising

The loan has not yet been funded. This typically represents the kind of loans we advertise on the front page of Kiva.org and on the Lend tab. Lenders can only lend to loans that are fundraising. You can find the amount funded so far by checking funded_amount.

funded

This loan request has been completely funded and is not available for new loans by lenders. The loan may be waiting for disbursal to the borrower(s), assuming the loan was posted to Kiva before the field partner disbursed the funds. The field funded_date shows the exact time at which the loan was fully funded on Kiva.

in_repayment

The loan has been disbursed to the borrowers and they are in the process of using the funds and making payments on the loan to the field partner. Loans in this state may see journal updates and lenders to this loan will get repayments when the borrower's payments are reconciled with Kiva.

paid

The loan has been paid back in full by the borrower. The payments have been distributed back to the lenders and the loan is closed to most new activity on Kiva.

defaulted

Occassionaly, a borrower or a field partner may fail to make payments on a loan, either to the field partner or to Kiva, respectively. Usually when this happens, a loan simply becomes delinquent and remains in the in_repayment status. 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.

refunded

It's rare, but occasionally Kiva needs to refund the funded portion of the loan to lenders after the loan has been partially funded, fully funded, or even during repayment. There are many reasons why a loan could be refunded, but usually it is because there is an error with the loan posting or the loan itself has been found to violate Kiva's policy for loans. Currently, you cannot search for loans based on this status.

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.

Loan Detail

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.

disbursal_amount

The amount of money distributed to the borrower(s) in the local currency. Comparing this amount to the loan amount shows the currency conversion rate locked in for the loan when it was posted.

disbursal_currency

The ISO 4217 code for the currency used to distribute the loan the the borrower. This is usually the local currency for the borrower's country.

disbursal_date

The date at which the funds from the loan were given to the borrowers. Note that it is possible for the money to be disbursed to borrowers before the loan is posted on Kiva.

loss_liability

A set of values which describes who is liable for loss on a loan, and how. For nonpayment, the party liable can either be the lender or partner. For currency_exchange the liability can be shared, fully resting on the partner, or none if the currency is locked to the US dollar. If currency exchange loss is a shared liability, the currency_exchange_coverage_rate will also be listed. (For more information on these topics, search for "default protection" or "currency exchange" at our Help Center.)

currency_exchange_loss_amount

If a currency exchange loss is shared between a partner and the lender, then this value represents the amount in USD lost by the lender due to fluctuations in the value of the local currency against the US dollar. This will result in the paid amount of loan being less than the full loan amount even when the status of the loan is listed as paid.

local_payments

A list of the payments the borrower will make to the field partner, also commonly called the “loan schedule” from the perspective of the borrower. Each payment has an amount (in local currency) and a due date (the approximate day and time the payment is due to the field partner).

scheduled_payments

A list of the payments (in US dollars) due to lenders and the dates when lenders can expect a repayment if the loan is not delinquent. This is considered the loan schedule from the lenders' point of view. Since both Kiva and the field partner work to facilitate the loan between the lender and the borrowers there is more than one way to represent the loan schedule.

payments

The list of payments that have been made by the borrower and that have been reconciled with Kiva's accounting system. A payment usually has an amount (in USD), a local amount (in the disbursal currency), a processed date (the approximate date at which the borrower paid the partner), and a settlement date (the date at which funds for payment from the partner were reconciled by Kiva). Payments might also have comments.

journal_totals

The values here show the number of total journal entries for the loan as well as the number which are automated or “bulk” entries. Bulk entries are typically much less interesting than other journal entries. Checking these counts can help you determine if it is worthwhile for your application to fetch the journals for a loan.

Also, there are a couple items which only apply to loans in fundraising status:

funded_amount

This is the amount of the loan which has been purchased by Kiva lenders. When this amount becomes equal to the loan_amount the loan moves to a funded state (soon followed by in_repayment).

basket_amount

This is the amount of the loan which lenders have saved in shopping baskets, but has not been confirmed as purchased. It is possible that in the near future a portion or all of this amount could become available to other lenders, but until that time this amount of the loan is reserved. In the case where funded_amount + basket_amount >= loan_amount you 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_amount and 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.)

Linking Loans back to Kiva.org

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:

where <id> is the ID of the loan you want to link.