Kiva API

kiva_api.py

import json
import unicodecsv
import requests

loan_ids_path = './loan_ids.csv'
# Kiva requests, but does not require, that developers use
# an app_id parameter in API requests. 
APP_ID = 'edu.northwestern.nick'

NUM_API_CALLS = 0

def reformat(json_object, translation_dict):
    new_object = dict()
    for new_key, get_key in translation_dict.iteritems():
        new_object[new_key] = get_key(json_object)
    return new_object

def get_json(url):
    r = requests.get(url)
    if r.status_code == 200:
        json_object = json.loads(r.content)
    else:
        return {}


def loan_lenders(loan_id):
    '''
    Typical JSON data structure returned:
    
    {
        lender_id: "alancheuk",
        name: "Alan",
        image: {
            id: 24981,
            template_id: 1
        },
        whereabouts: "Burnaby British Columbia",
        country_code: "CA",
        uid: "alancheuk"
    },

    >>> loan_lenders(84)
    25: [u'michael', '_anonymous', u'ward', '_anonymous', u'brooke']
    '''
    # We'll anticipate possibly integer loan_id values,
    # maybe we should let it fail. 
    if type(loan_id) != unicode:
        loan_id = unicode(loan_id)

    json_translation = {'lender_id':            lambda x: x.get('lender_id', ''),
                        'name':                 lambda x: x.get('name', ''),
                        'image_id':             lambda x: x['image']['id'],
                        'image_template_id':    lambda x: x['image']['template_id'],
                        'whereabouts':          lambda x: x.get('whereabouts', ''),
                        'country_code':         lambda x: x.get('country_code', ''),
                        'uid':                  lambda x: x.get('uid', '')}
    
    # The basic Kiva API query to get the list of lenders
    # for a particular loan, as selected by the loan ID.        
    url = 'http://api.kivaws.org/v1/loans/%s/lenders.json&app_id=%s' % (loan_id, APP_ID)
    
    json_object = get_json(url)
    # Use the reformat() function with the json_translation dictionary
    # to go from the nested JSON data structure to a flat Python dict.
    lenders = [reformat(lender, json_translation) for lender in json_object.get('lenders', [])]
    
    # Each request provides a max of 20 lenders, so we need to iterate
    # through the rest of the pages. 
    if 'paging' in json_object:
        page_count = int(json_object['paging']['pages'])
        for page_number in range(2, page_count):
            # Only the query URL changes to add the parameter for page number
            json_object = get_json(url + '&page=%d' % page_number)
            lenders += [reformat(lender, json_translation) for lender in json_object['lenders']]
    return lenders