In addition to our specialized data objects, there are some very simple data types that are helpful to understand when working with the API.
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).
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:
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.
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.
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.
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.
geoelement for a loan requested in Tursunzade, Tajikistan:
As you can see, our
geo element has 3 components; they are defined as such:
exact. Use this information to help you decide how to represent the data, or if you should do your own geocoding for the object.
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.