as3Kiva is a simple API wrapper in Actionscript 3 for accessing data from the Kiva API.

The wrapper class provides easy methods to get the data from the Kiva API in the desired format and converts the result to its relative AS3 object

html=>String, json=>Object, xml=>XML

Requirements

as3corelib : this opensource as3 library is used to deserialize .json strings returned by the KivaAPI to AS3 objects.

note : for now please make sure you always pass in the "page" parameter for all methods in the wrapper.

Description

The KivaWrap class is the primary API wrapper class that contains all methods for getting data from the Kiva API. When a request to the api is made and a valid result is returned, the class dispatches an event of the type associated with the particular method called. Refer to the table below for methods and their associated even types.

setup

import com.humsara.kiva.KivaWrap;
import com.humsara.kiva.KivaWrapEvent;

// instantiate KivaWrap
var kivaAPI:KivaWrap = new KivaWrap();

// set returnType:String - possible values KivaWrap.TYPE_XML, KivaWrap.TYPE_JSON, KivaWrap.TYPE_HTML
//   returnType is defaulted to TYPE_JSON
kivaAPI.returnType = KivaWrap.TYPE_JSON;

// set dispatchMode:String - possible values 
//   KivaWrap.DISPATCH_UNIQUE : *default* each method dispatches a unique KivaWrapEvent type (look at method table below) 
//   KivaWrap.DISPATCH_COMPLETE : all methods dispatch KivaWrapEvent.COMPLETE type
//   KivaWrap.DISPATCH_BOTH : both unique and complete event types are dispatched
kivaAPI.dispatchMode = KivaWrap.DISPATCH_BOTH;

// set formatResult:Boolean  - default true
//   The kivaAPI returns data as a serialized string.  It is up to the application to
//   parse the string into a usable format.  KivaWrap.as by default will convert json
//   and xml serialized strings to AS3 Object() and AS3 XML() types respectively. 
//   Should you desire to not do so and simply access the string returned by the kivaapi
//   set this variable to false; 
//   Otherwise you can leave this statement out, since the default value is true;
kivaAPI.formatResult = true;

// set appID:String  - the KivaAPI requests as good practice to send in an application
//   id whenever a call is made.  By default the appID is set to "com.humsara.as3.kivaAPIwrap"
kivaAPI.appID = "com.mydomain.myappname";

lets make a call to get a list of the newest loans on kiva : getNewestLoans

// create listener for getNewestLoans method
kivaAPI.addEventListener ( KivaWrapEvent.LOAN_NEWEST, onGetLoans );
// make the call to the api
kivaAPI.getNewestLoans ();

// create handler function for when loan data is returned
function onGetLoans ( evt:KivaWrapEvent ):void {
    // the requested data is in the property of name "data"
    var jsonData:Object = evt.data;  // if returnType = KivaWrap.TYPE_JSON
    //var xmlData:XML = evt.data;      // if returnType = KivaWrap.TYPE_XML
    //var htmlData:String = evt.data;  // if returnType = KivaWrap.TYPE_HTML

    // ... write your code to process the data here
}

difference between dispatchModes DISPATCH_UNIQUE && DISPATCH_COMPLETE

/** 
 *  DISPATCH COMPLETE
 *  This method would be used if you want to use one handler for all methods 
 */

kivaAPI.dispatchMode = KivaWrap.DISPATCH_COMPLETE;
// creating this listener will send all result events to the kivaResultsHandler function
kivaAPI.addEventListener ( KivaWrapEvent.COMPLETE, kivaResultsHandler );

// all api calls will send a KivaWrapEvent.COMPLETE event 
kivaAPI.getLenderDetails ( ['lenderID1','lenderID2','lenderID3'] );
kivaAPI.getLoanLenders ( 234524 );

// function to handle all methods
function kivaResultsHandler ( ev:KivaWrapEvent ):void {
    // here we have one function to handle all call but we still need to be able 
    // to tell which method was called that resulted in this dispatch
    // so we can know how to properly read the data.
    // For that we use the reqType property in the 'ev' argument
    
    switch ( ev.reqType ) {
        case KivaWrapEvent.LENDER_DETAILS:
            // your code to handle lender details from ev.data
            break;
        case KivaWrapEvent.LOAN_LENDERS:
            // your code to handle a list of lenders from ev.data
            break;
    }
}

/** 
 *  DISPATCH UNIQUE
 *  This method would be used if you want to create separate handler functions for
 *  different api calls.  
 *  This is the default method of dispatching and the one I personally prefer.
 */

kivaAPI.dispatchMode = KivaWrap.DISPATCH_UNIQUE;

// create an event listener for getLenderDetails
kivaAPI.addEventListener ( KivaWrapEvent.LENDER_DETAILS, handleLenderDetails );

// create an event listener for getLoanLenders
kivaAPI.addEventListener ( KivaWrapEvent.LOAN_LENDERS, handleLoanLenders );

// call the functions to get the data from KivaAPI
kivaAPI.getLenderDetails ( ['lenderID1','lenderID2','lenderID3'] );
kivaAPI.getLoanLenders ( 234524 );

// function to handle getLenderDetails results
function handleLenderDetails ( ev:KivaWrapEvent ):void {
    // your code to handle lender details from ev.data

}

// function to handle getLoanLenders results
function handleLoanLenders ( ev:KivaWrapEvent ):void {
    // your code to handle a list of lenders from ev.data
}

or you can set dispatchMode = KivaWrap.DISPATCH_BOTH

to dispatch both unique and complete events.

Kiva API to as3kiva method map

Additional Methods and Properties

KivaWrap.getImageURL ( imageID:Number, size:String = KivaWrap.IMG_200x200 ):String

Provided an imageID and a KivaAPI approved image size, the function returns the URL to access the image from Kiva.

The approved image sizes have been provided as static constants in the KivaWrap class

KivaWrap.IMG_80x80

KivaWrap.IMG_200x200

KivaWrap.IMG_325x250

KivaWrap.IMG_450x360

KivaWrap.IMG_FULLSIZE

import com.humsara.kiva.KivaWrap;
var myImageURL:String = KivaWrap.getImageURL ( 9381, KivaWrap.IMG_FULLSIZE);

other static variables of KivaWrap.as

public static const TYPE_XML:String = "xml";
public static const TYPE_JSON:String = "json";
public static const TYPE_HTML:String = "html";
public static const SORT_NEW:String = "newest";
public static const SORT_OLD:String = "oldest";
public static const SORT_POPULARITY:String = "popularity";
public static const SORT_LOAN_AMOUNT:String = "loan_amount";
public static const SORT_EXPIRATION:String = "expiration";
public static const SORT_AMOUNT_REM:String = "amount_remaining";
public static const SORT_REPAYMENT_T:String = "repayment_term";
public static const SORT_RECOMMENDATION_C = "recommendation_count";
public static const SORT_COMMENT_C = "comment_count"
public static const MEDIA_ANY = "any";
public static const MEDIA_VIDEO = "video";
public static const MEDIA_IMAGE = "image";
public static const STATUS_FUNDRAISING = "fundraising";
public static const STATUS_FUNDED = "funded";
public static const STATUS_IN_REPAYMENT = "in_repayment";
public static const STATUS_PAID = "paid";
public static const STATUS_DEFAULTED= "defaulted";

Search Methods : "params" parameter explaination

There are four methods for searching data from the api. searchJournals, searchLenders, searchLoans, and searchTeams. Each of these search functions accepts a pageNumber as its first argument, and an object containing additional search parameters as allowed by the kiva api.

The accepted variables in the params object are the same as those specified in the KivaAPI documentation.

Please refer to the linked references to the KivaAPI for acceptable values for each parameter and further details.

I have created static variables for some of the values I found myself using the most, like SORT_NEW,SORT_OLD etc.. for the 'sort_by' parameter, or STATUS_FUNDRAISING, STATUS_PAID etc for the 'status' parameter

searchJournals ( page:Number=1, params:Object=null )

• params: q,sort_by,media,include_bulk,partner

• params: q,sort_by,country_code,occupation

• params: q,sort_by,status,gender,region,country_code,sector,partner,has_currency_loss

• params: q,sort_by,membership_type,category

Sample usage for searchLoans

var searchParams:Object = { sort_by:KivaWrap.SORT_AMOUNT_REM, region:["ca","sa"],has_currency_loss:false };
kivaAPI.searchLoans(1,searchParams);