Getting Started

Here are some tips to help you get started.

Step 1: Read the developer Terms Of Service and Code Of Conduct

We know you are eager to start working with code, but it is important that you read and understand the Terms of Service and Code of Conduct. Start with these to make sure the application you have in mind is in the spirit of our terms for use of the API.

Step 2: Play around with the loan search method

Our API methods can be tested easily with most any browser. As an example, try out the loans/search method using HTML output:

http://api.kivaws.org/v1/loans/search.html?status=fundraising

API calls with the .html extension are designed for testing or debugging. If the browser or tool you are using easily supports viewing XML output you might try using the .xml extension instead:

http://api.kivaws.org/v1/loans/search.xml?status=fundraising

Try changing up some of the parameters and see how the search results change. Here are some of the parameters that the loans/search method can take:

status

Any of: fundraising,funded,in_repayment,paid,defaulted

gender

Any of: male,female

sector

Matches against a sector name such as agriculture

region

Any of: na,ca,sa,af,as,me,ee

country_code

Matches a two-digit ISO country code.

partner

Matches one or more partner IDs.

q

A general search string to match against various properties of loans

sort_by

Any of: popularity,loan_amount,oldest,expiration,newest, amount_remaining,repayment_term

page

A number for the page of data to return (results are segmented into pages).

Here's how you'd make a request for all loans in Cambodia or Mongolia that are actively paying back, sorted by the amount of the loan:

http://api.kivaws.org/v1/loans/search.html?country_code=kh,mn&sort_by=loan_amount&status=in_repayment

Step 3: Check out a sample application

We haven't been able to put together a ton of sample applications yet, but we do have this iPhone web app for you to check out (works best with Safari):

http://socialology.org/dashapps/kiva/

This is a simple application designed with Dashcode that lets you see a short list of fundraising loans on Kiva and explore details on each of those loans. We think it is a handy staring point for demonstrating what you can do with the Kiva API and hopefully it gets the gears turning on an idea of your own.

If you are feeling particularly adventurous, feel free to inspect the source code for the application to see specifically how it calls and uses the Kiva API. The application works completely client-side using JavaScript so there is no hidden code on the server (except for a simple Ruby script which serves as a proxy for the cross-domain API calls).

Step 4: Start designing your application!

Think about the experience you'd like to create for Kiva users. Maybe you want to create a notification system for a particular type of loan; perhaps you let your users specify the kind of loan about which to be notified. Maybe you have an idea for a creative way to show off Kiva's statistics or activity on the site. The application might be as simple as a widget for a blog that shows off loans you've recently made on Kiva. Taking a look at the KIVA API Reference will help you in your design by showing you what kind of data is available.

Once you have a rough idea sketched out for your application, you'll want to dig deeper into the documentation, particularly:

• understanding our API conventions
• familiarizing yourself with the terminology we use for the various kinds of data