Fetching Data

Simple Data Types

In addition to our specialized data objects, there are some very simple data types that are helpful to understand when working with the API.

IDs

Most data objects have unique IDs so you can track them and refer to them later. For example, every loan has a loan ID. This is an obvious yet powerful part of the API. When the field is simply called "id" we're usually referring to an integer used to refer to an object like a loan or an image. Other types of IDs are unique strings that you can also use to refer to a data object; examples of these include a lender_id (for referencing a lender) and youtube_id (which references a video on YouTube).

Dates

All dates in the Kiva API are represented as timestamps according to ISO 8601. Here's an example of what a date looks like in this format:

2009-01-09T09:50:08Z

The dates are usually in UTC as represented by the 'Z' time zone designator at the end of the string. Most programming languages have open source libraries or built-in support for handling the ISO 8601 format.

Images and Other Media

Things like images are too complex to represent in a simple data response. Instead, media is stored separately and we give you information on how to access it or integrate it into your application. Images, for example, are represented by an ID and a template URL. We talk more about how to access images in a following section.

Country and Language Codes

Countries and languages are represented by codes in the API rather than using their full English name. This is true for API responses as well as parameters. Countries are coded according to ISO 3166-1-alpha-2. Languages may be specified as two or three characters according to the IANA Language Subtag Registry and RFC 4646.

Location

We think location is a real cool property of the objects our data represents. Many of our data responses have location information built into them, including geospatial information. A location object typically has conventional information like the name of a town or country related to its parent (i.e., a Loan). In most cases, we also provide a geo element which is based on the GeoRSS Model for geospatial information.

Here's a sample of the geo element for a loan requested in Tursunzade, Tajikistan:

As you can see, our geo element has 3 components; they are defined as such:

level

Reflects the level of accuracy available for the supplied geometry. Popular values might be town, country, or exact. Use this information to help you decide how to represent the data, or if you should do your own geocoding for the object.

type

The type of geometry defined by the coordinate pairs provided. This can be any of the shapes supported by the GeoRSS Model — point, line, box, or polygon.

pairs

The coordinate pairs for the geometry. This value is formatted according to the GeoRSS-Simple specification for serializing coordinates. For example, in the sample above a point is represented by latitude, followed by longitude, and separated by a space.

Whearabouts

In comparison to location, whereabouts are some sort of vague notion we have about the location or origin of the related data. Currently, lender data has a “whereabouts” field to convey the information a lender has supplied about where he is from. Since we can't vouch for the accuracy or meaning of this data, and we don't have a good way of resolving it to some place on the globe, we just call it “whereabouts.” We figured you'd get the point.