API Reference

This is reference documentation for all methods exposed by the Kiva API.

GET /journal_entries/:id/comments

Returns comments for a specified journal entry.

Example

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

Parameters

id(number)
Required. The ID number of the journal entry for which you want comments.
page(number)
The page position of results to return.
  • Default: 1
app_id(string)
A unique developer-defined Application ID, usually in reverse DNS notation.

Response

  comment – HTML , JSON , XML

GET /journal_entries/search

Sort and filter all journal entries based on multiple criteria.

Example

http://api.kivaws.org/v1/journal_entries/search.json

Parameters

media(string)
If provided, filters results to those having the type of media specified.
  • One of: any, video, image
include_bulk(boolean)
If true, includes auto-generated journal entries in the results.
partner(list of strings)
If provided, filters results to only those having partners in this list.
sort_by(string)
The order by which to return the results.
  • One of: newest, oldest, recommendation_count, comment_count
  • Default: newest
q(string)
A query string used to match journal entries’ content.
page(number)
The page position of results to return.
  • Default: 1
app_id(string)
A unique developer-defined Application ID, usually in reverse DNS notation.

Response

  journal_entry – HTML , JSON , XML

GET /lenders/:lender_ids

Retrieves detail for multiple lenders.

Example

http://api.kivaws.org/v1/lenders/matt.json

Parameters

lender_ids(list of strings)
Required. A list of Lender IDs for which to return details.
  • Max list items: 50
app_id(string)
A unique developer-defined Application ID, usually in reverse DNS notation.

Response

  lender_detail – HTML , JSON , XML

GET /lenders/:lender_id/loans

Returns loans belonging to a particular lender.

Example

http://api.kivaws.org/v1/lenders/jeremy/loans.json

Parameters

lender_id(string)
Required. The Lender ID for which to return loans.
    page(number)
    The page position of results to return.
    • Default: 1
    sort_by(string)
    The order by which to sort results.
    • One of: oldest, newest
    • Default: newest
    app_id(string)
    A unique developer-defined Application ID, usually in reverse DNS notation.

    Response

      loan_listing – HTML , JSON , XML

    GET /lenders/:lender_id/teams

    Returns teams that a particular lender is a member of.

    Example

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

    Parameters

    lender_id(string)
    Required. The Lender ID for which to return teams.
      page(number)
      The page position of results to return.
      • Default: 1
      app_id(string)
      A unique developer-defined Application ID, usually in reverse DNS notation.

      Response

        team_detail – HTML , JSON , XML

      GET /lenders/newest

      Returns listings for the lenders who have most recently joined Kiva.

      Example

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

      Parameters

      page(number)
      The page position of results to return.
      • Default: 1
      app_id(string)
      A unique developer-defined Application ID, usually in reverse DNS notation.

      Response

        lender_listing – HTML , JSON , XML

      GET /lenders/search

      Search and sort lender listings based on multiple criteria.

      Example

      http://api.kivaws.org/v1/lenders/search.json

      Parameters

      country_code(list of strings)
      An ISO country code by which to filter results.
        sort_by(string)
        The order by which to sort the results.
        • One of: oldest, newest
        • Default: newest
        q(string)
        A general search query parameter which matches against lenders’ names occupations, whereabouts, and reasons for lending.
        occupation(string)
        If supplied, results are filtered by those that match lenders’ occupation. This parameter is ignored if the "q" parameter is supplied.
        page(number)
        The page position of results to return.
        • Default: 1
        app_id(string)
        A unique developer-defined Application ID, usually in reverse DNS notation.

        Response

          lender_listing – HTML , JSON , XML

        GET /lending_actions/recent

        Lists the 100 most recent loans made on Kiva by public lenders.

        Example

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

        Parameters

        app_id(string)
        A unique developer-defined Application ID, usually in reverse DNS notation.

        Response

          lending_action – HTML , JSON , XML

        GET /loans/:ids

        Returns detailed information for multiple loans.

        Example

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

        Parameters

        ids(list of numbers)
        Required. A list of the loan IDs for which to return detail.
        • Max list items: 10
        app_id(string)
        A unique developer-defined Application ID, usually in reverse DNS notation.

        Response

          loan_detail – HTML , JSON , XML

        GET /loans/:id/journal_entries

        Retrieve journal entries associated with a particular loan.

        Example

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

        Parameters

        id(number)
        Required. The ID of the loan for which you want journal entries.
        include_bulk(boolean)
        Set true to include automatically generated journal entries.
        • Default: 1
        page(number)
        The page position of results to return.
        • Default: 1
        app_id(string)
        A unique developer-defined Application ID, usually in reverse DNS notation.

        Response

          journal_entry – HTML , JSON , XML

        GET /loans/:id/lenders

        Returns the list of public lenders to a loan.

        Example

        http://api.kivaws.org/v1/loans/38239/lenders.json

        Parameters

        id(number)
        Required. The loan ID for which to return lenders.
        page(number)
        The page position of results to return.
        • Default: 1
        app_id(string)
        A unique developer-defined Application ID, usually in reverse DNS notation.

        Response

          lender_listing – HTML , JSON , XML

        GET /loans/:id/updates

        Returns all status updates for a loan, newest first.

        Example

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

        Parameters

        id(number)
        Required. The loan ID for which to return updates.
        app_id(string)
        A unique developer-defined Application ID, usually in reverse DNS notation.

        Response

          loan_updates – HTML , JSON , XML , RSS

        GET /loans/newest

        Returns a simple list of the most recent fundraising loans.

        Example

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

        Parameters

        page(number)
        The page position of results to return.
        • Default: 1
        app_id(string)
        A unique developer-defined Application ID, usually in reverse DNS notation.

        Response

          loan_listing – HTML , JSON , XML

        GET /loans/search

        Search and sort loan listings by multiple criteria.

        Example

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

        Parameters

        status(list of strings)
        The status of loans to return.
        • One of: fundraising, funded, in_repayment, paid, defaulted
        gender(list of strings)
        If supplied, results are filtered to loans with entrepreneurs of the specified gender. In the case of group loans, this matches against the predominate gender in the group.
        • One of: male, female
        region(list of strings)
        A list of two-letter codes corresponding to regions in which Kiva operates. If supplied, results are filtered to loans only from the specified regions.
        • One of: na, ca, sa, af, as, me, ee
        country_code(list of strings)
        A list of two-character ISO codes of countries by which to filter results.
          sector(list of strings)
          A list of business sectors for which to filter results.
          partner(list of numbers)
          A list of partner IDs for which to filter results.
          sort_by(string)
          The order by which to sort results.
          • One of: popularity, loan_amount, oldest, expiration, newest, amount_remaining, repayment_term
          • Default: newest
          q(string)
          A query string against which results should be matched.
          has_currency_loss(boolean)
          If true, only returns loans for which lenders have lost value due to fluctuations in currency exchange. This limits results to loans which are in repayment, paid, or defaulted.
          page(number)
          The page position of results to return.
          • Default: 1
          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            loan_listing – HTML , JSON , XML

          GET /methods

          Lists all methods available via the Kiva API.

          Example

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

          Parameters

          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            method_summary – HTML , JSON , XML

          GET /methods/:ids

          Lists all methods available via the Kiva API.

          Example

          http://api.kivaws.org/v1/methods/GET*|methods|:ids.json

          Parameters

          ids(list of strings)
          Required. The IDs of methods for which to return specifications.
          • Max list items: 50
          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            method_summary – HTML , JSON , XML

          GET /partners

          Returns detailed listings for all Kiva field partners.

          Example

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

          Parameters

          page(number)
          The page position of results to return.
          • Default: 1
          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            partner_listing – HTML , JSON , XML

          GET /releases/api/current

          Returns versioning information on the current Kiva API release.

          Example

          http://api.kivaws.org/v1/releases/api/current.json

          Parameters

          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            release – HTML , JSON , XML

          GET /teams/:ids

          Returns detailed information about one or more lending teams.

          Example

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

          Parameters

          ids(list of numbers)
          Required. A list of team IDs for which to return team detail.
          • Max list items: 20
          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            team_detail – HTML , JSON , XML

          GET /teams/:id/lenders

          Returns the list of public lenders belonging to a specific team.

          Example

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

          Parameters

          id(number)
          Required. The numeric team ID for which to return lenders.
          sort_by(string)
          The order by which to sort results.
          • One of: oldest, newest
          • Default: newest
          page(number)
          The page position of results to return.
          • Default: 1
          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            lender_listing – HTML , JSON , XML

          GET /teams/:id/loans

          Returns loans belonging to a particular team.

          Example

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

          Parameters

          id(number)
          Required. The team ID for which to return loans.
          page(number)
          The page position of results to return.
          • Default: 1
          sort_by(string)
          The order by which to sort results.
          • One of: oldest, newest
          • Default: newest
          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            loan_listing – HTML , JSON , XML

          GET /teams/search

          Sort through the list of lending teams using multiple criteria.

          Example

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

          Parameters

          membership_type(string)
          If supplied, only teams with the specified membership policy are returned.
          • One of: open, closed
          category(string)
          If supplied, only teams with the specified category are returned.
          sort_by(string)
          The order by which to sort results.
          • One of: newest, oldest, member_count, loan_count, loaned_amount
          • Default: newest
          page(number)
          The page position of results to return.
          • Default: 1
          q(string)
          A query string by which to match results.
          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            team_listing – HTML , JSON , XML

          GET /teams/using_shortname/:shortnames

          Returns detailed information about one or more teams, identified by shortname.

          Example

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

          Parameters

          shortnames(list of strings)
          Required. A list of team shortnames for which to return team detail.
          • Max list items: 20
          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            team_detail – HTML , JSON , XML

          GET /templates/images

          Lists all URL templates useful for fetching images on Kiva.

          Example

          http://api.kivaws.org/v1/templates/images.json

          Parameters

          app_id(string)
          A unique developer-defined Application ID, usually in reverse DNS notation.

          Response

            image_template – HTML , JSON , XML

          Kiva
          • © 2009 Kiva. All rights reserved.
          • Terms Of Service
          • Kiva is a 501(c)(3) nonprofit.