Images and other media at Kiva are composed of an immense amount of data as compared with other types of data in the Kiva API. Since it's not reasonable to embed this data in our API responses, and since most people want to embed images in applications and web pages anyway, we have a simple template system for referencing images.
An image in the Kiva API is represented by an
id and a
template_id. For example, here's a
sample image reference for a borrower picture:
The specific template you can use for an image can depend on the photo. This photo uses the image template with ID
1 which looks like this:
The ID part of the template makes sense, but what about the size? For any image at Kiva, you can choose any value for the size. These are the options:
When you request an image that is not one of the standard sizes used on Kiva's site, the request will cause that image to be generated and cached.
If you use one of our standard sizes, the image will already be pre-cached on our server and returned faster. Our standard sizes are:
For each of the values that specify both height and width, you will get an image whose maximum dimension is scaled to
the value supplied. For an image that is 800 pixels wide and 600 pixels high, using
provide an image sized to 80 pixels wide and 60 pixels high.
fullsizereturns the largest version of the
image available. For the "s<dimension>" (ex: "s300")
pattern, you will get a squared image (in this example: 300px x 300px). Squared images are handy for various
layout types, such as Kiva's home page. A word of caution: squared images can sometimes crop people out of the
photo; for wide photos, the cropping routine cuts off the left and right sides evenly. This can sometimes crop
individuals out if they
are on the sides which is especially common in group photos. If the image is tall, the cropping routine cuts the
bottom of the photo off since most images of borrowers have their heads in the top part of the photos. Squared
images are good for certain layout types, but when showing a "zoomed in" version, it's best to use the other
sizing options to prevent cropping people out.
Knowing the template pattern, we can put the values together and create an image URL from our template:
1. From where do templates come? As it turns out, we have an API method for that too. Since we expect the number of image templates we use to be small, we have one simple method that returns them all of them to you at once:
A good practice would be to cache the output from this call in your application and only refresh it when you see a template ID that isn't in your cached version. (We promise we'll never change the value of a template for given ID.) You could take things a step further and include a cached version as a part of your application's data resources. Since we currently only use one template ID for all the images at Kiva, it's possible that your app would never refresh the template list for images! However, a robust application would be prepared for the introduction of a new template at any time.
Kiva supports video only in loan profiles and journal entries at the moment. You won't find a video for every loan or journal entry, but when you do it will look like this:
Videos don't have templates. Instead we refer you to the YouTube API for information on how to embed, present, or otherwise handle video in your application. Currently all video at Kiva is hosted by YouTube.
A thumbnail image for every video is available. Currently the thumbnail image is the same as the primary image for the loan or journal entry.