Fetching Data

Introduction

The Kiva API is concerned with helping you find and present data from Kiva. We want to help you find things like loans, lenders, and partners and help you represent those in your applications and products. We think there are a lot of really useful things that can be done just by helping the Kiva community find information in different ways or experience it in a new context.

In talking about data, we'll start by defining some common terms used by the API and how that relates to the language on the Kiva website. Then, we'll explain some of the data types in more detail and write about some practical approaches on putting the different types of data calls together.

(PS, if you're just interested in working with RSS, you might want to skip ahead to Feeds).

Objects in the Kiva World

Loans, lenders, entrepreneurs, businesses… all of these terms can get a bit overwhelming without a proper introduction. When we created the Kiva API we wanted to choose terminology that was objective and easy to understand from a developer (and sometimes, finance) perspective. This means that the language on the Kiva website may not always match up with the terminology in the API – the Kiva website is a dynamic, evolving user experience but the API should be a consistent tool on which your own dynamic applications can depend.

Loan

A loan is the most important data object at Kiva. Most other objects are in some way related to a loan. It makes sense; facilitating loans that change lives is at the heart of Kiva's mission. You've probably seen loans referred to as “businesses” or “entrepreneurs” in other places because of the tight relationship between all these concepts. However, in the API, if you want to show a listing of any of these things in your application you should think about fetching and rendering loan objects. For example, from an API perspective, the Lend tab at Kiva.org shows a listing of loans, and the front page of Kiva features a entrepreneur by fetching a loan that is currently fundraising.

Borrower

A borrower is someone who has requested a loan. We often refer to these individuals as “entrepreneurs” at Kiva because we believe strongly in the entrepreneurial spirit of our borrowers working to make a difference in their lives. A loan may have more than one borrower, and in this case the loan is considered a “group loan.”

Lender

A lender is a user registered on the Kiva website for the purposes of lending money and participating in the community. Most lenders have public profiles, or Lender Pages, on Kiva where they can share a bit about what they do and why they lend. Not all lenders have made loans, and not every lender has opted to display public information. Lenders without public information are referred to as "anonymous" lenders.

Partner

A partner, or Kiva Field Partner, is a microfinance institution with whom we work to find and fund loans. Every loan at Kiva is offered by a partner to a borrower, and the partner works with Kiva to get funding for that loan from lenders. The association of a loan to a partner is very important since the risk associated with a loan correlates closely to the reputation of a partner. This is why every partner has a risk rating.

Journals and Journal Entries

Every loan has a journal where Kiva or a partner can provide updates about a loan. Each of these updates is called a “journal entry.” Some journal entries have photos or videos associated with them and provide personal updates about a borrower. Others are more informational or automated updates and are classified as “bulk” journal entries. Lenders can post comments on journal entries.

Team

Lenders can coordinate their activity on Kiva through Lending Teams, found on the Kiva community tab. Teams are usually formed around a common interest (sometimes related to lending, sometimes not) or may represent real-world groups outside of Kiva such as a church or a classroom. Currently, most team activity is centered around making loans as every lender can credit a loan to one team every time a loan is made. As such, teams are associated with both teams and lenders. Teams also have profile information, similar to lenders, where they post a team photo and why the team has come together to loan.

Simple Data Types

In addition to our specialized data objects, there are some very simple data types that are helpful to understand when working with the API.

IDs

Most data objects have unique IDs so you can track them and refer to them later. For example, every loan has a loan ID. This is an obvious yet powerful part of the API. When the field is simply called "id" we're usually referring to an integer used to refer to an object like a loan or an image. Other types of IDs are unique strings that you can also use to refer to a data object; examples of these include a lender_id (for referencing a lender) and youtube_id (which references a video on YouTube).

Dates

All dates in the Kiva API are represented as timestamps according to ISO 8601. Here's an example of what a date looks like in this format:

2009-01-09T09:50:08Z

The dates are usually in UTC as represented by the 'Z' time zone designator at the end of the string. Most programming languages have open source libraries or built-in support for handling the ISO 8601 format.

Images and Other Media

Things like images are too complex to represent in a simple data response. Instead, media is stored separately and we give you information on how to access it or integrate it into your application. Images, for example, are represented by an ID and a template URL. We talk more about how to access images in a following section.

Country and Language Codes

Countries and languages are represented by codes in the API rather than using their full English name. This is true for API responses as well as parameters. Countries are coded according to ISO 3166-1-alpha-2. Languages may be specified as two or three characters according to the IANA Language Subtag Registry and RFC 4646.

Location

We think location is a real cool property of the objects our data represents. Many of our data responses have location information built into them, including geospatial information. A location object typically has conventional information like the name of a town or country related to its parent (i.e., a Loan). In most cases, we also provide a geo element which is based on the GeoRSS Model for geospatial information.

Here's a sample of the geo element for a loan requested in Tursunzade, Tajikistan:

"geo": { "level": "town" "type": "point" "pairs": "38.5 68.2333" }

As you can see, our geo element has 3 components; they are defined as such:

level
Reflects the level of accuracy available for the supplied geometry. Popular values might be town, country, or exact. Use this information to help you decide how to represent the data, or if you should do your own geocoding for the object.
type
The type of geometry defined by the coordinate pairs provided. This can be any of the shapes supported by the GeoRSS Model — point, line, box, or polygon.
pairs
The coordinate pairs for the geometry. This value is formatted according to the GeoRSS-Simple specification for serializing coordinates. For example, in the sample above a point is represented by latitude, followed by longitude, and separated by a space.

Whearabouts

In comparison to location, whereabouts are some sort of vague notion we have about the location or origin of the related data. Currently, lender data has a “whereabouts” field to convey the information a lender has supplied about where he is from. Since we can't vouch for the accuracy or meaning of this data, and we don't have a good way of resolving it to some place on the globe, we just call it “whereabouts.” We figured you'd get the point.

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:

http://api.kivaws.org/v1/loans/newest.json

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:

{ "name": "Le Thi Tan", "location": { "country": "Viet Nam", "geo": "16.1667 107.833", "town": "Quang Xuong" }, "posted_date": "2009-01-09T09:50:08Z", "activity": "Poultry", "id": 80735, "use": "Buy more ducks and chickens ", "description": { "languages": [ "vi", "en" ] } }, "funded_amount": 125, "partner_id": 67, "image": { "template_id": 1, "id": 243961 }, "borrower_count": 1, "loan_amount": 550, "status": "fundraising", "sector": "agriculture" }

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:

http://api.kivaws.org/v1/partners.json

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.

http://api.kivaws.org/v1/loans/search.json?partner=71

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:

http://api.kivaws.org/v1/loans/search.json?partner=65,84,37&status=fundraising

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:

http://www.kiva.org/lend/<id>?app_id=<app_id>

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

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.

Media

Images and other media at Kiva are composed of an immense amount of data as compared with other types of data in the Kiva API. Since it's not reasonable to embed this data our API responses, and since most people want to embed images in applications and web pages anyway, we have a simple template system for referencing images.

Images

An image in the Kiva API is represented by an id and a template_id. For example, here's a sample image reference for a borrower picture:

"image": { "id": 181707, "template_id":1 }

The specific template you can use for an image can depend on the photo. This photo uses the image template with ID 1 which looks like this:

http://www.kiva.org/img/<size>/<id>.jpg

The ID part of the template makes sense, but what about the size? For any image at Kiva, you can choose any value for the size. These are the options:

  • Specify height: http://www.kiva.org/img/h300/691404.jpg the width will be automatically chosen based on the aspect ratio of the original image.
  • Specify width: http://www.kiva.org/img/w300/691404.jpg the height will be automatically chosen based on aspect ratio.
  • Specify both: http://www.kiva.org/img/h300w300/691404.jpg the image will be resized to fit inside that space, which means that for images that aren't 1:1 width/height ratios, one of the dimensions will be less than what you requested.
  • Squared http://www.kiva.org/img/s300/691404.jpg the image will be returned as a square.
  • Full Size http://www.kiva.org/img/fullsize/691404.jpg Get the full size image.

When you request an image that is not one of the standard sizes used on Kiva's site, the request will cause that image to be generated and cached.

If you use one of our standard sizes, the image will already be pre-cached on our server and returned faster. Our standard sizes are:

  • w80h80
  • w200h200
  • w325h250
  • w450h360
  • s300
  • fullsize

For each of the values that specify both height and width, you will get an image whose maximum dimension is scaled to the value supplied. For an image that is 800 pixels wide and 600 pixels high, using w80h80 will provide an image sized to 80 pixels wide and 60 pixels high. fullsizereturns the largest version of the image available. For the "s<dimension>" (ex: "s300") pattern, you will get a squared image (in this example: 300px x 300px). Squared images are handy for various layout types, such as Kiva's home page. A word of caution: squared images can sometimes crop people out of the photo; for wide photos, the cropping routine cuts off the left and right sides evenly. This can sometimes crop individuals out if they are on the sides which is especially common in group photos. If the image is tall, the cropping routine cuts the bottom of the photo off since most images of borrowers have their heads in the top part of the photos. Squared images are good for certain layout types, but when showing a "zoomed in" version, it's best to use the other sizing options to prevent cropping people out.

Knowing the template pattern, we can put the values together and create an image URL from our template:

http://www.kiva.org/img/w200h200/181707.jpg

Image URL Templates

In the example above we showed you the image template with ID 1. From where do templates come? As it turns out, we have an API method for that too. Since we expect the number of image templates we use to be small, we have one simple method that returns them all of them to you at once:
http://api.kivaws.org/v1/templates/images.json

A good practice would be to cache the output from this call in your application and only refresh it when you see a template ID that isn't in your cached version. (We promise we'll never change the value of a template for given ID.) You could take things a step further and include a cached version as a part of your application's data resources. Since we currently only use one template ID for all the images at Kiva, it's possible that your app would never refresh the template list for images! However, a robust application would be prepared for the introduction of a new template at any time.

Since there is only one image template ID (1) in the Kiva API you might cache this in your application, but be prepared to fetch an updated template list if you see a new one in the future.

Video

Kiva supports video only in loan profiles and journal entries at the moment. You won't find a video for every loan or journal entry, but when you do it will look like this:

"video": { "id": 383, "youtube_id":"Yu_moia-oVI" }

Videos don't have templates. Instead we refer you to the YouTube API for information on how to embed, present, or otherwise handle video in your application. Currently all video at Kiva is hosted by YouTube.

A thumbnail image for every video is available. Currently the thumbnail image is the same as the primary image for the loan or journal entry.

More

Lending Actions

Lending actions are cool bits of data that we've offered on the front page of Kiva for a while. On the website we've called this “recent activity” and you might have seen us call these “transactions” as well. Basically, a lending action is the singular action of a lender making a loan to an entrepreneur on Kiva. It's comprised of an ID, a loan listing, a lender listing, and a date at which the lending action was completed.

Currently, only the 50 most recent lending actions are available via the API through this call:

http://api.kivaws.org/v1/lending_actions/recent.json

A lender might make any loan amount or even a few loans to the same entrepreneur but it will show up as one lending action. Also, lending actions made more than 48 hours ago or those by anonymous lenders are not shown.

Journal Entries and Comments

A loan can have any number of journal entries. These are updates about the status of the loan, the borrower, or sometimes, the field partner. Also, visitors to the Kiva site (not necessarily lenders) can make comments to a journal entry. Journal entries are typically accessed by passing in the ID for a specific loan:

http://api.kivaws.org/v1/loans/42939/journal_entries.json

The methods for fetching journal entries take an optional parameter, include_bulk. By default this is set to 0 since we assume that in mose cases you're not interested in boring automated notifications (often these are triggered by payments made to a loan – information you can fetch from a loan's detail). However, to get bulk entries as well as the meatier entries, just set this parameter to 1.

Each journal entry listing will have a comment_count field showing the number of comments posted to the entry. Since most entries don't have comments, you can use this to only fetch comments for entries with comments or those that appear to have especially lively discussion around them. The call to fetch comments for a journal entry only requires a journal entry ID (which is guaranteed to be unique for every journal, regardless of loan). Such a call looks like this:

http://api.kivaws.org/v1/journal_entries/28342/comments.json

Teams

A lending team is comprised of a number of lenders, and at least one lender (the team captain). Lenders come together in a team to pool their lending toward a common cause or interest, and as such, teams are also related to loans. Teams are identified by a numerical ID, but can also have an customizable alias, called a shortname, which may also be used for identification. Typically you get information about a team using the numeric team ID:

http://api.kivaws.org/v1/teams/2.json

You can get the list of lenders in a team by passing in the same ID to this call:

http://api.kivaws.org/v1/teams/2/lenders.json

and the loans atrributed to the team are fetched in similar way:

http://api.kivaws.org/v1/teams/2/loans.json

If a user happens to know the shortname of their team, it's also possible to do a lookup of team information using that alias instead of the team ID:

http://api.kivaws.org/v1/teams/using_shortname/buildkiva.json

Team API methods are a work in progress - we should have more soon that allow reverse lookup (such as finding out which teams a lender belongs to...)

Protected Resources

Accessing & Using Protected Resources

Introduction

Most of the resources available through the Kiva API are public and unprotected. In fact, most of the data about our partners, lenders, and borrowers is made public as we strive to make lending as transparent as possible. As a result, most apps only need access to public data from the Kiva API to build compelling experiences. However when a developer wishes for a part of his application to target a specific Kiva customer (usually, a Kiva lender) then it can be interesting to broker access for the user to his private account data via the Kiva API by accessing protected resources.

Applications wanting to access protected resources should consider very carefully how they will use private data in their application. Even the most well-intentioned applications could violate the user's expectations around how their data is handled simply through poor design. Moreover, inadequate privacy measures, poor knowledge of network security issues, lazy coding, and bugs can expose private data and violate a user's trust. We take our user's privacy very seriously and we require the same approach to user data from our developers. As such, we've devote the first few topics here to guide you in designing and implementing secure, responsible applications. Applications that handle user private data poorly weaken the Kiva community and are very likely a violation of the Kiva and Kiva API terms of service.

Private user data is protected via OAuth in the Kiva API. OAuth is an industry standard mechanism by which a user can delegate and control access to protected resources on the Internet to applications that request it. Your application issues such a request directly to the user via the Kiva API and if the request is approved, your application is immediately issued special access credentials by Kiva. It's important to note that the user can revoke these credentials at any time. Accessing protected resources in the Kiva API requires a working knowledge of the related OAuth standards we've employed, including OAuth 1.0a, MAC tokens, and HTTPS. Fortunately, we've included a wealth of information here to refresh the veterans and to get newbies up to speed.

Kiva uses OAuth 1.0a to control application access to protected resources. OAuth is an industry standard that allows a user to authorize an application to act their behalf with certain permissions. OAuth gives the user a great deal of control and security in that the application never has full access to their account, passwords, or other credentials and that the user can revoke the application's access to their account any time using their Kiva account preferences.

Using protected resources demands skill and caution. But, with a little effort, they can be a powerful addition to your app. If you're up to the challenge, continue on…

Storing Secrets Securely

To use the OAuth protocol you are required to store secret tokens. Your app will be issues a client secret and you will be granted an access token secret for each user. You must be able to store these securely in your application. If your app writes to databases on client devices, such as mobile phones, you must encrypt any token secrets you store. If you how don't do this, your app will be insecure and expose your apps users to having their private Kiva data exposed. If you are unsure how to encrypt data on your platform, post in the forum

Private Data & Your App

We can’t stress enough how important it is to us to protect the private data of our users. If your app is granted access to such data by a user, we expect you to take the same approach. Kiva user private data can include sensitive identifying information such as name, physical location or email address, as well as financial details such account balances, loan transaction, monetary losses, and gifts to other individuals. It could even include data confidential between a borrower and the lenders to a loan. That Kiva deals with personal financial data and financial transactions between users ups the ante for everyone. It's important that developers accessing such data respect user privacy and make the proper efforts to protect it.

How do I know what data is private?

The types of private data accessible to developers may fluctuate as we deploy new release of the API. To keep things simple, we define private data as any resource that can be accessed or modified under these URL prefixes:

https://api.kivaws.org/v1/my
https://api.kivaws.org/partner

Thus, if you accessed data from an endpoint prefixed by either of these URL paths, you should treat that data as private. Some of the same information may be available through other Kiva APIs (e.g., location, number of loans, name) but you can never be certain if the user has hidden this information in their public profile unless you also access the data from a public URL. Therefore, when you access data from a protected URL, keep it private. If you want to need to display data about a user (or partner) publicly access a public URL instead.

How should private data be used in my application?

Private data should be viewed and used only by the user to whom it belongs. This means your application should be designed in such a way that access can be protected from users other than the owner. There are also important security measures that every application should take. As a guiding rule, if your applications accesses protected Kiva resources, you should protect these resources & data with same vigilance as Kiva. While not an exhaustive list, here's a checklist that should help make sure we're on the same page:

  1. Use HTTPS/SSL - Most applications will transfer application code, data and user data over the public Internet. Just as all protected resources of the Kiva API are only available over HTTPS your application should only use HTTPS (or similarly SSL-secured connections) when transferring data between your server and the browser or native client.
  2. Web apps need user authentication - If your app displays or manages private user data at a long-lived URL accessible on the public internet, you must secure access to that URL with appropriate authentication. In most cases this means requiring login with a username/password or using a trusted sign-on provider such as Facebook, Twitter, or Kiva itself.
  3. Avoid caching private data - Network traffic is often cached at some level without our control. But, you can prevent exposure to data leaks by limited how much you actively cache data for a user. Apps can cache data in cookies, local browser storage, hard disks, or other app sandboxes. In doing so, you increase the chances that another app or a security hole will expose the data on the device. Apps may also cache data on the server and thus expose the user through their own site vulnerabilities.
  4. Don't publicly post private data or derivative data - With the wealth of social networks and forums available it is tempting to help the user share exciting and interesting data on places like Twitter, Facebook, and blogs. Don't post user public data to publicly places without very specific and conscious consent. Even sharing conclusions from the private data such as "John has credit to reloan!" may be more than the user expects to share and is certainly a private account detail not available to others on Kiva.org.
  5. Always require user consent to modify or access private data - Whether your app is making a loan or simply displaying an account balance on the screen, the result can be upsetting for a user if he didn't expect the result. Your application should take a specific action only after confirming user consent. This may be indicated by a button, a dialog, or well-defined gesture. The more sensitive or destructive the action, the more difficult the action should be. For example, a clickable item called "View my Account" might be a reasonable action for retrieving and revealing account details to the user. By contrast making a loan should require multiple deliberate actions such as dragging an item to a basket, clicking "Checkout," and then reviewing and confirming the transaction before processing the final result.

These are just a few of guidelines to get you started in thinking about how private data will be incorporated into your app. Before we dig deeper into best practices and security guidelines, it first helps to understand how applications are authorized to use protected resources, and how they authenticate with Kiva after authorization.

OAuth and Access Tokens

Requesting Protected Resources with an Access Token

Once your application is granted an access token, it is easy to then access protected resources on behalf of a Kiva User or a Kiva Partner. The process is as simple as generating an Authorization header for your resource request using the token and adding it to the Authentication header for your HTTPS request.

We strongly recommend that you used an existing library or open source code that is well tested to sign your requests. If you are writing your own implementation, it is essential that you also review the official documentation.

User Resources

A Kiva User is simply someone who has an account on Kiva and is able to make to take actions on Kiva such as make a loan, buy a gift card, send another user a message, or join a lending team. Typically, Kiva Users also opt to have a public profile page. Most users are Kiva Lenders, but it is important to distinguish that "lender" may only be one role of a particular Kiva User and, in fact, not all Kiva users may participate in lending. Some Kiva Users may only participate in administrative tasks such as posting or translating loans or managing a lending team.

The main private resource for users is their account information:

https://api.kivaws.org/v1/my/account

When requested using a valid OAuth access token, this resource (available as HTML, JSON, or XML) is returned as a data structure , similar to a Lender object, having these properties:

  • id - This is a unique numerical ID that distinguishes the user account from all other accounts. This number never changes.
  • is_public - True if the user has a public Lender Profile. False if the user is Anonymous.
  • first_name - The first name of the user.
  • last_name - The legal last name of the user.
  • lender_id - This is the name the user chooses to display publically. Equivalent to the 'name' property on a Lender object.

Here's an example of a User Account object in JSON

{ "user_accounts":[ { "id":123456, "is_public":true, "first_name":"John", "last_name":"Smith", "lender_id":"john9999", } ] }

Data Snapshots

Important Note: As of April 11, 2012, snapshot generation is happening again, but intermittent. We'll update this message when they snapshots are back on a regular schedule.

If you want to work with a lot of Kiva's data, making hundreds or thousands of requests to the Kiva API can be overbearing — both for you and your network. As such, we make much of our data available through snapshots which are compressed into a simple singular download. The data is archived nightly so it is most useful for apps that don't require live data, such as data analyses and visuals. However, some applications might find these handy as a way to seed local data sources, supplementing the snapshots with calls to the Kiva API for the most recent data.

A data snapshot is composed of multiple files, delivered in a single compressed ZIP archive. Data snapshots are available in XML and JSON, just like responses in the Kiva API. For the most part, the format of the documents in the snapshots are the same as an API response, with a few exceptions.

Downloading Snapshots

The latest data snapshots are available in the format of your choice at the following URLs:

JSON: http://s3.kiva.org/snapshots/kiva_ds_json.zip

XML: http://s3.kiva.org/snapshots/kiva_ds_xml.zip

Archive Structure

When you decompress and extract a data snapshot you'll have a collection of documents with the following structure:

kiva_ds_json/ lenders/ 1.json 2.json 3.json 4.json ... loans/ 1.json ...

At the root level of the snapshot is a collection of directories, one each for the type of data archived. For now, we simply capture detailed data about a singular object such as a loan or lender. In the future, there might be data collections for relational data, such as lenders_to_loan. Each of these data collections is a series of numbered files in the chosen format, JSON or XML. Together all of these files make up the complete data collection as if we captured the data in a single file (e.g., lenders.json). The complete data set is broken up into multiple files so it is easy to process the data with conventional parsers.

The number of each file in the collection corresponds to the page of data in the series, much like pages of data accessed through the Kiva API. So, lenders/2.json would be similar to http://api.kivaws.org/v1/lenders/search.json?page=2. The only difference is that the page size used in data snapshots is much larger than that in the Kiva API.

File Format

As mentioned, the format of data in each snapshot document is similar to that of a response in the Kiva API. The main difference is the way the data segment is wrapped and how meta-data is expressed for each segment of the snapshot. Here's an example of the beginning of a sample document, lenders/2.json:

{ "header":{ "total":"444938", "page":2, "date":2009-06-20T04:50:29Z, "page_size":1000 } ,"lenders":[ { ...

The structure begins with a header element which contains meta-data for this snapshot segment. We see the total number of elements in the data collection, 444938, as well as the date of the snapshot (which should be identical for all documents in the snapshot). We read from the header that size of each data page is 1000 elements (in this case, lender elements) so we know there are 445 total pages (ceiling of total/page_size). The page number of the document is also reinforced in the header.

Afterwards, follows an ordered array of lender elements, sorted from oldest to newest. Each of these elements is identical to a detailed lender record in the Kiva API.

The XML version of snapshots is a direct translation of the JSON format shown above. The root node used for XML documents is <snapshot>.

Data Rate and Throttling

Access to the Kiva API is throttled to the limits below.

Unregistered Apps 60 requests per minute
Registered Apps * 500 requests per minute

*You can register your app here

If you exceed the throttle limits, the Kiva server will respond with:

403 Forbidden (Rate Limit Exceeded)

Requests from that IP address will be temporarily locked out.

You can find out how many requests you have available for the next 60 seconds by checking the HTTP response headers. e.g.

X-RateLimit-Overall-Limit: 500 X-RateLimit-Overall-Remaining: 497

The above exmaple means you are throttled to 500 requests per minute and have 497 left for the next 60 seconds.

Particular endpoints may also have a specific throttle in addition to the overall throttle. e.g.

X-RateLimit-Specific-Limit: 60 X-RateLimit-Specific-Remaining: 57

The above exmaple means you are throttled to 60 requests per minute and have 57 left for the next 60 seconds.

If you find yourself being throttled, we recommend implementing an Exponential Backoff algorithm.

If you require access to the Kiva database, try our snapshots or contact us at build_kiva@kiva.org.

RSS Feeds

Feeds give you access to Kiva's data in a very simple format that many tools and applications already know how to use. We've specifically designed these for folks casual users, feed mashers, and anyone else looking for syndicated content in RSS form.

Feeds are subject to many of the same conventions as the API, but the format of the responses are very different. Rather than sticking to very strict rules about how data is formatted, feeds focus on making syndicated information human-readable within a wide range of applications. As a result, if you find feeds aren't giving you the control you want over presenting data, you might want to check out our other response formats.

We provide feed formats for API calls in cases where we think a wide range of users can get a lot of milage out of the the data using existing tools and apps. The Kiva API currently only supports the RSS 2.0 format which we assume that either you or your reader already know how to use. All requests for RSS data end in the extension rss, for example:

http://api.kivaws.org/v1/loans/76950/updates.rss

We're still in the process of updating all of our feeds to snazzy new versions based on the Kiva API. In the meantime, you'll find the formal documentation for both our new and legacy RSS feed collection. We've documented how to call each feed and what inputs, if any, it takes. For detail on the RSS returned by each, we encourage you to call the feed and take a look at the results.

loans/:id/updates

Returns a mix of items sorted by age from newest to oldest. Each item describes some event in the lifetime of the loan, typically a journal entry or information about a repayment.

Example:
http://api.kivaws.org/v1/loans/76950/updates.rss

Parameters

id
the unique identifier of the loan for which you want detail

Code Samples and SDKs


Code samples


Kiva Supported


PHP, Python, JavaScript

Code samples can be found in our GitHub repository here:

Feel free to update and extend our code. Pull requests are welcomed!

Third-Party Supported


Node.JS

SDKs

There are a number of SDKs for easy access to our APIs.

Kiva Supported


JavaScript

Third-Party Supported


Temboo

Temboo offer an SDK for iOS, Java/Android, Node.js, PHP, Python, and Ruby.
Temboo Kiva SDKs

PHP
Python
Java
Ruby

oEmbed

oEmbed is a simple standard that makes it easy to embed a small alternate version of a web page in various other contexts. At Kiva, we currently support oEmbed for our borrower profile pages.

What's it for?

The first site to take advantage of our oEmbed support was Twitter. You can read about what they were able to do with it in their blog post.

How it works

oEmbed requests occur between two parties: a consumer makes the request, and a provider returns a response. To construct an oEmbed request, the consumer has to know a scheme and an endpoint. Using the scheme and endoint, the consumer can construct a URL like this:

http://www.kiva.org/services/oembed?url=http%3A//www.kiva.org/lend/100000
The provider then returns a response, generally in XML or JSON, conforming the oEmbed spec. In this case, the consumer would get back a response including:
"version":"1.0", "type":"rich", "title":"Kiva - Bibi Najeba Group's Loan", "width":450, "height":300, "html":" <-- xhtml fragment to be embedded, omitted here for brevity --> "

The consumer can use this data to render a version of a resource as an embedded widget. To learn more about how oEmbed works, check out the oEmbed spec.

Kiva scheme and endpoint:

We currently support oEmbed for one URL scheme, which is our borrower profile page.

Scheme
http://www.kiva.org/lend/*
Endpoint
http://www.kiva.org/services/oembed

Optional parameters

All requests to the endpoint must include a "url" parameter conforming to a supported scheme. In addition, the following optional parameters are supported

format
One of ("json" | "xml" | "jsonp"* | "preview"**) The default is "xml"
maxwidth
See the oEmbed spec. Usually unnecessary
maxheight
See the oEmbed spec. Usually unnecessary
jsonp *
Required if format is "jsonp". This is the name of the jsonp callback to use.

* nonstandard. Jsonp support makes it easier to use oEmbed in a client-side application, but is not entirely without risk for the consumer.

** nonstandard. Returns the html fragment only, as an aid during development.

Discovery

Our oEmbed support is discoverable. The <head> of the borrower profile page includes two <link> tags that point to the corresponding xml and json oEmbed URLs, like this:
<link rel="alternate" type="application/json+oembed" href="http://www.kiva.org/services/oembed?url=http%3A%2F%2Fwww.kiva.org%2Flend%2F100000&format=json" title="Bibi Najeba Group's Loan from Afghanistan (JSON oEmbed view)" /> <link rel="alternate" type="text/xml+oembed" href="http://www.kiva.org/services/oembed?url=http%3A%2F%2Fwww.kiva.org%2Flend%2F100000&format=xml" title="Bibi Najeba Group's Loan from Afghanistan (XML oEmbed view)" />
Kiva
  • © 2009 - 2014 Kiva. All rights reserved.
  • Terms Of Service
  • Kiva is a 501(c)(3) nonprofit.