PhpKiva is a simple PHP5 library for accessing data from Kiva API.It presents a simple object oriented interface to query the Kiva API to obtain results in the formats supported by Kiva-.json,.xml and .html
Requirements
- Php5
- curl
Description
Kiva API has been built around 4 primary objects in the Kiva World.PhpKiva extends a Php class for all 4 objects, providing functionalities on all those 4 objects.Here is a list of Kiva Objects and their corresponding PhpKiva classes:
- Loan - This is the primary object of the Kiva API. The corresponding mapping in PhpKiva for the loan object is the class KivaLoan in Loan.php
- Lender - Another highly important component which is mapped as class KivaLender in Lender.php
- Partner - Object for Kiva Partners(MFI's) represented as class KivaPartner in Partner.php
- Journal Entry - Wrapped as class KivaJournalEntry in JournalEntry.php
For the query string of all API calls, the phpKiva interface takes an equivalent array of (key,value) pair and constructs a query string from it so that the users of the phpKiva API can work with standard PHP arrays itself.
Loan
| Kiva API Call | phpKiva equivalent method | Parameters |
| loans/newest | getRecentLoans($params) | $params(optional): Array of optional parameters : 'page' there is one parameter, a string having it also works |
| loans/(ids) | getLoansInfo($ids) | $ids(required) : array of ids((upto 10 supported by Kiva Api)) to fetch info for. |
| loans/(id)/lenders | getLenders($id,$params) | $id(required) : id of the loan for which lender information is required. $params(optional) : Array of optional parameters : 'page' there is one parameter, a string having it also works |
| loans/(id)/journal_entries | getJournalEntries($id,$params) | $id(required) : The identification number for a loan $params(optional) : Array of optional parameters : 'page','include_bulk' |
| loans/search | searchLoans($params) | $params(optional) : Array of optional parameters : 'page','status','gender','sector','region','country_code','partner','q' To provide a list of 'sector','region' construct an array within the main array at these keys |
| loans/(id)/updates | getStatusUpdates($id) | $id(required) |
Lender
| Kiva API Call | phpKiva equivalent method | Parameters |
| lenders/(lender_ids) | getLendersInfo($ids) | $ids(required) : array of ids((upto 10 supported by Kiva Api)) to fetch info for. |
| lenders/(lender_id)/loans | getLenderLoans($id,$params) | $id(required) : The lender ID of a kiva lender $params(optional) : Array of optional parameters : 'sort_by','page' |
| lenders/newest | getRecentLenders($params) | $params(optional) : Array of optional parameters : 'page' there is one parameter, a string having it also works |
| lenders/search | searchLenders($params) | $params (optional): Array of optional parameters : 'page','sort_by','occupation','country_code','q' |
Partner
| Kiva API Call | phpKiva equivalent method | Parameters |
| partners | getPartners($params) | $params(optional) : Array of optional parameters : 'page' there is one parameter, a string having it also works |
JournalEntry
| Kiva API Call | phpKiva equivalent method | Parameters |
| journal_entries/(id)/comments | getComments($id,$params) | $id (required): id of the journal entry |
Installation
All the above classes sub-class from a base class implemented in ApiConnector.php. Hence, in order to use a particular php file, the ApiConnector.php would also be required.So here are the step-by-step directions for using the API:
- Download ApiConnector.php
- Download the corresponding php file for the Kiva object that you plan to use.For instance, if you are building an application dealing only with Lender information, then you only need the class KivaLender in Lender.php and hence, downloading just that file would suffice.However, if you plan to use more than one type of Kiva Object, then you require multiple classes and hence, the corresponding files.
- Simple include them in your code using for instance: require 'Loan.php'.
- Instantiate the object and set the return format (json,xml,html) in which you want the desired ouput.By defauly, phpKiva returns results from Kiva in XML format.However, that can easily be changed while instantiating the object or by using the setReturnType function
Examples
require 'lender.php';
$lenderObj = new KivaLender();
if($lenderObj->setReturnType("html")){
$response = $lenderObj->getRecentLenders("page=2");
echo $response;
}
